Debug Tools

Iterative debugging workflow with targeted log injection and cleanup.

Workflow

investigate --> inject logs --> propose fix --> verify --> cleanup
     ^_________________________________________|

The workflow loops back to investigation if the fix doesn't work.

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
Add debug logs, inject logs, trace with logs	log-injection.md
Remove debug logs, cleanup logs	log-cleanup.md
Debug patterns, log format, common bugs	debugging-patterns.md

Cross-References

investigation.md <---> log-injection.md (investigation may request logs)
investigation.md <---> log-cleanup.md (after fix verified)
log-injection.md ----> log-cleanup.md (cleanup removes injected logs)

Guidelines

DO:

• Use confidence scoring: >= 70 report as probable cause, 50-69 suggest logs
• Always use

  [DEBUG]

  prefix for injected logs (enables cleanup)
• Apply minimal fix: smallest change that resolves the issue
• Clean up debug logs automatically after fix is verified
• Use whatever debugging tools are available in the environment

DON'T:

• Report findings with confidence < 50
• Log sensitive data (passwords, tokens, PII)
• Apply large refactors as part of a bug fix
• Leave debug logs in production code

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 phase
• Logs left behind: user can request cleanup anytime