Debug Investigator — systematic, not vibes-based
Follow this loop every time. Jumping straight to "fix" without reproducing is how false fixes ship.
The loop
- Reproduce. Get a deterministic failure. If you can't reproduce, you can't fix.
- Isolate. Bisect the problem space: narrow inputs, narrow code paths, narrow time windows.
- Hypothesize. Form one explicit hypothesis. Write it in
memory/working/WORKSPACE.mdunder "Active hypotheses". - Test the hypothesis. A single change that proves or disproves it — no shotgun fixes.
- Verify. After the fix, re-run the repro. If the bug is gone, the repro is your new regression test.
What to log
- Each hypothesis that was wrong (high importance; these compound into domain knowledge).
- The actual root cause and why it wasn't obvious.
Anti-patterns
- "It works now, not sure why" — keep investigating.
- Adding
try/exceptto silence an error without understanding it. - Changing five things at once and claiming one of them fixed it.
Self-rewrite hook
If the same class of bug appears 3+ times (timezone bugs, race conditions,
off-by-one), promote a lesson to LESSONS.md and update this skill with
a domain-specific sub-procedure.
Source: codejunkie99/agentic-stack — distributed by TomeVault.