mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-11 19:47:12 +03:00

Files

T

Magnus Hedemark 1e9fd74ea7 feat: add systematic-debugging skill — 4-phase root cause protocol

Adapted from obra/superpowers (Jesse Vincent, MIT) and expanded with
real-world debugging patterns from production use. Core additions:

Phase 1 sub-steps for common failure modes:
- Schema/environment divergence (test vs production schema diffing)
- Exception type specificity (sibling exception traps in Pyhton)
- Progressive characterization grid (isolate retrieval failures variable by variable)
- Dependency source detection (editable dev forks causing schema drift)
- Systematic web research protocol (structured search before guessing)
- macOS sandboxed app debugging (containers, XPC, TCC, iCloud sync)
- Trace data flow upstream from the symptom

Key heuristics:
- Rule of Three: 3+ failed fixes = question the architecture
- Red Flags table: 12 rationalizations to catch yourself making
- Investigation Flow: keep pushing, don't break momentum to ask questions

Includes two worked example references (dev fork detection, macOS Books.app).

Signed-off-by: Jasper <magnus@groktop.us>

2026-05-21 22:46:32 -04:00

2.5 KiB

Raw Permalink Blame History

Worked Example: Detecting an Editable Dev Fork

Demonstrates the "Check Dependency Source" pattern (Phase 1, step 5d).

The Symptom

A background worker crashed on every invocation:

Traceback ...
  File "core/session.py", line 456, in _create_node
    cursor.execute("""INSERT INTO thought_nodes
    (id, content, node_type, timestamp, confidence, source_file, ...)
sqlite3.OperationalError: table thought_nodes has no column named confidence

The Investigation Path

Read the traceback — the error is in core/session.py (a third-party library), line 456. It's trying to insert a confidence column that doesn't exist in the database.
Check the schema — sqlite3 brain.db ".schema thought_nodes" confirmed no confidence column in the actual table. The schema had id, content, node_type, timestamp, source_file, decayed, ... but no confidence.
Check the source — python3 -c "import core.session; print(core.session.__file__)" revealed the library was loading from /private/tmp/some-fork/core/session.py — not from site-packages.
Check dependency source — pip show cashew-brain revealed:
- Editable project location: /private/tmp/some-fork
- Version: 1.0.0
- This is a pip install -e dev copy in a temp directory
Compare to upstream — pip index versions <package> showed a newer version on PyPI. The installed dev copy was behind and had un-merged changes.

The Fix

The initial instinct was to patch the migration code in the dev copy — treating it as a bug in the code. The correct answer was: the dev copy shouldn't be there. The fix was:

pip uninstall <package> -y
pip install <package>          # install from PyPI
python3 -c "import <module>; print(<module>.__file__)"
# → site-packages/<module>/  ✓ production path

After switching to production, the INSERT no longer referenced confidence at all — the dev fork's schema drift was gone.

Key Lesson

The confidence column had been added to INSERT statements in the dev fork, but the corresponding ALTER TABLE ADD COLUMN migration was never written. This is classic schema drift from an unmaintained fork. The symptom looked like a code bug, but the root cause was dependency management — running the wrong version of the library.

Verification Commands

# Check install source
pip show <package>

# Check import path
python3 -c "import <module>; print(<module>.__file__)"

# Check PyPI for comparison
pip index versions <package>

# Check DB schema for drift
sqlite3 <db_path> ".schema <table_name>"

2.5 KiB Raw Permalink Blame History