debug

Debug Mode

Systematic diagnosis and root cause fixing. Activated automatically when debugging signals detected.

Methodology

NEVER guess. Always investigate.

Phase 1: Reproduce

1. Confirm the error exists
2. Get exact error message/behavior
3. Identify minimal reproduction steps
4. Note: works in X, fails in Y?

Phase 2: Isolate

1. What changed recently?
2. Binary search: which commit/change introduced it?
3. Smallest code path that triggers issue?
4. Environment-specific? (versions, configs, data)

Phase 3: Instrument

1. Add logging at key points
2. Check assumptions (values, types, state)
3. Trace execution path
4. Compare expected vs actual at each step

Phase 4: Root Cause

1. WHY is this happening, not just WHAT
2. Is this a symptom of deeper issue?
3. Why didn't we catch this earlier?

Phase 5: Fix + Verify

1. Fix the root cause, not the symptom
2. Verify fix works
3. Check for regressions
4. Add test to prevent recurrence

Anti-patterns

• Random changes hoping something works
• Fixing symptoms instead of causes
• Skipping reproduction ("I saw it once")
• Not checking assumptions
• Fixing without understanding

Output Behavior

When debugging:

• Write findings to file (not terminal dump)
• Log: hypothesis → test → result
• Terminal: brief status updates only
• Final fix: explain what was wrong and why

Integration

If project has kernel/banks/DEBUGGING-BANK.md, load it for deep methodology.