ctaxnagomi Systematic Debugging
A structured 4-phase approach to debugging that forces understanding before fixing. Prevents the common trap of jumping to solutions without grasping the actual problem.
When to Use
- A bug is reported and you need to find the root cause
- Something works locally but fails in production
- Intermittent issues that are hard to reproduce
- Any situation where "just try stuff" has failed
Procedure
Phase 1: Reproduce
- Get the exact steps to reproduce the bug
- Confirm you can reproduce it yourself
- Note the environment, inputs, and outputs
Phase 2: Hypothesize
- List 3-5 possible root causes
- For each, identify what evidence would confirm or rule it out
- Rank by likelihood based on the symptoms
Phase 3: Investigate
- Test each hypothesis systematically
- Add logging or debugging output as needed
- Narrow down to the single root cause
- Stop when you have evidence, not just a guess
Phase 4: Fix and Verify
- Write a test that reproduces the bug
- Implement the minimal fix
- Confirm the test passes
- Check for regressions
Pitfalls
- Fixing symptoms instead of root causes
- Skipping the reproduction step
- Changing multiple things at once
- Not writing a regression test
Verification
- The original bug no longer reproduces
- The new test passes
- Existing tests still pass
- You can explain the root cause in one sentence
How to use?
1. Download
Go to the AGENT KD SKILL gallery and find this skill card. Click Download to save the SKILL.md file.
2. Install
Copy the downloaded SKILL.md into your agent's skills directory:
| Agent | Path |
|---|---|
| Hermes | ~/.hermes/skills/hermes/systematic-debugging/SKILL.md |
| opencode | ~/.config/opencode/skills/systematic-debugging/SKILL.md |
| Claude Code | ~/.claude/skills/systematic-debugging/SKILL.md |
3. Use
Restart your agent session. The skill will auto-load when debugging is needed.
4. Verify
Ask your agent to debug something. If it follows the 4-phase approach, you're all set.