Systematic Debugging
Solve complex issues using the rigorous /debug workflow.
Overview
Section titled “Overview”The /debug workflow enforces a 4-phase investigation protocol (Discovery, Hypothesis, Verification, Resolution). It prevents guess-driven development by requiring evidence before code changes.
ℹ️
When to use:
- “The login button does nothing”
- “API returns 500 error intermittently”
- “App crashes on mobile only”
The Process
Section titled “The Process”1
Discovery
Gathers facts: Error logs, user reports, reproduction steps.
/debug Login returns 403 even with correct credentials2
Hypothesis
Formulates potential causes prioritized by likelihood.
3
Verification
Systematically tests each hypothesis using scripts or logs.
4
Resolution
Implements the fix and adds a regression test.
Example Session
Section titled “Example Session”agent-session
$
/debug Form submission fails silently
▸
Phase 1: Discovery
Reading
CheckoutForm.tsx… Found handleSubmit.ERROR: Cannot read properties of undefined
▸
Phase 2: Hypothesis
1.
emailRef.current is null on mount2. Event handler not bound correctly
▸
Phase 4: Resolution
Fix applied: Added null check to
emailRef.✅ Test passed: Form submits successfully.
Pro Tips
Section titled “Pro Tips”💡
Provide Context
Paste the exact error message or stack trace for faster discovery.
💡
Trust, Verify
Ask the agent to run the reproduction case again to confirm it’s solved.
Next Steps
Section titled “Next Steps”- Try
/debugon an existing bug - See Deployment to ship your fix