Debug Tools
Iterative debugging workflow with flexible technique selection and escalation.
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.
Context Loading Strategy
Load only the reference matching the current trigger. Multiple references may be loaded during a full debugging session (investigation often leads to log injection).
Triggers
| Trigger Pattern | Reference |
|---|---|
| Debug issue, investigate bug, fix bug | investigation.md/debug-tools/references/investigation.md) |
| Add debug logs, inject logs, trace with logs | log-injection.md/debug-tools/references/log-injection.md) |
| Remove debug logs, cleanup logs | log-cleanup.md/debug-tools/references/log-cleanup.md) |
| Debug patterns, log format, common bugs | debugging-patterns.md/debug-tools/references/debugging-patterns.md) |
Cross-References
investigation.md <---> log-injection.md (investigation may request logs)
investigation.md <---> log-cleanup.md (after fix verified)
investigation.md <---> debugging-patterns.md (pattern comparison)
log-injection.md ----> log-cleanup.md (cleanup removes injected logs)Guidelines
DO:
- Use confidence scoring: >= 70 report as probable cause, 50-69 suggest logs
- Compare broken code against working examples when root cause is unclear
- Always use
[DEBUG]prefix for injected logs (enables cleanup) - Apply minimal fix: smallest change that resolves the issue
- Redact sensitive values (passwords, tokens, PII) in injected logs
- Clean up debug logs automatically after fix is verified
- Track fix attempts: after 3 failed fixes, escalate on the 4th to architectural review
- Use whatever debugging tools are available in the environment
DON'T:
- Report findings with confidence < 50 (contrasts: >= 70 probable cause, 50-69 suggest logs)
- Log sensitive data (contrasts: redact sensitive values in injected logs)
- Apply large refactors as part of a bug fix (contrasts: smallest change that resolves the issue)
- Leave debug logs in production code (contrasts: clean up debug logs after verification)
- Keep retrying the same approach when fixes fail repeatedly (contrasts: track attempts and escalate on the 4th)
Error Handling
- No bug description provided: ask user to describe the issue
- Cannot reproduce: suggest adding debug logs
- Fix doesn't work: return to investigation with new evidence
- Three failed fix attempts: escalate to architectural review on the next attempt
- Logs left behind: user can request cleanup anytime