| name | debug-tools |
| description | Evidence-led debugging for unexpected, silent, or intermittent failures. Use when tracing bugs, adding targeted logs, or verifying fixes. Not for known one-line fixes, runtime review of deployed services, or PM bug triage. |
Debug Tools
Iterative debugging workflow with flexible technique selection and escalation.
Triggers
- Debug a bug ("debug this", "investigate", "trace issue", "fix bug", "why is X broken") → investigation.md
- Add debug logs ("add debug logs", "inject logs", "trace with logs") → log-injection.md
- Cleanup logs ("remove debug logs", "cleanup logs") → log-cleanup.md
- Pattern lookup ("debug patterns", "common bugs", "used to work") → debugging-patterns.md
Multiple references may load during one debugging session — investigation often leads to log injection, then back to investigation.
Workflow
investigate → fix → verify → done
^_______________________| (max 3 attempts, then escalate)
Core loop: investigate, fix, verify. Techniques (log injection, pattern comparison, focus area analysis) are tools within investigation, not mandatory phases. Log cleanup happens automatically after verification succeeds.
A sensitive value never reaches an injected log — passwords, tokens, API keys, PII, session identifiers. This binds anywhere a log is added, including mid-investigation without the injection workflow loaded.
Anti-Pattern: Symptom Whack-a-Mole
Fixing the same symptom in multiple places signals an architectural issue, not a localized bug. When fix N introduces bug N+1, stop. The 4th attempt must escalate to architectural review: re-examine the abstraction, the missing layer, or the flawed assumption — not retry a deeper version of the same approach.
