| name | engram-systematic-debugging |
| description | Systematic debugging with engram evidence trails. Store investigation as reasoning chains — queryable and reviewable by future agents. |
Systematic Debugging
Per-turn write rule: After every bash (command run), read (file examined), edit, or write call, store what you found with engram_context_create or engram_reasoning_create + engram_relationship_create before ending the turn. Each phase below has an explicit write step — do not skip them.
Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
The Four Phases
Phase 0: Search First
engram_ask query="<error message or bug description>"
engram_ask query="<affected file> bug"
Don't duplicate prior investigations.
Phase 1: Root Cause Investigation
engram_task_create title="Debug: <issue description>" priority="high"
engram_task_update id=<TASK_UUID> status="in_progress"
Step 1: Reproduce the error. Store raw output:
engram_context_create title="Error: <brief>" content="Error: <full message>\nStack: <trace>\nReproducible: YES/NO" source="<file:line>"
engram_relationship_create source_id=<TASK_UUID> source_type=task target_id=<CTX_UUID> target_type=context relationship_type=relates_to agent="<name>"
Step 2: Check recent changes:
engram_context_create title="Recent changes: <area>" content="Recent commits touching affected files:\n- ..." source="git-log"
engram_relationship_create ...
Step 3: Examine the code. Store observations.
Phase 2: Pattern Analysis
engram_ask query="<error type> pattern similar bugs"
engram_context_create title="Pattern analysis: <error type>" content="Similar issues: ...\nRecurring pattern: <yes/no>" source="pattern-analysis"
engram_relationship_create ...
Phase 3: Hypothesis Testing
One hypothesis at a time:
engram_reasoning_create title="Hypothesis: <root cause>" task_id=<TASK_UUID> content="Hypothesis: ...\nEvidence: ...\nTest: <command>\nExpected: ..."
engram_relationship_create ...
Run the test. Store result:
engram_reasoning_create title="Hypothesis result: <statement>" task_id=<TASK_UUID> content="Conclusion: VERIFIED / REFUTED\nNext: ..."
engram_relationship_create ...
If refuted, form next hypothesis. If stuck: engram_next
Phase 4: Implementation (only after root cause confirmed)
engram_reasoning_create title="Fix: <root cause>" task_id=<TASK_UUID> content="Fix applied: ...\nFiles: ...\nRegression test: ..."
engram_relationship_create ...
Phase 5: Validate and Close
engram_validate
engram_task_update id=<TASK_UUID> status="done"
