Systematic Debugging

Solve complex issues using the rigorous /debug workflow.

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

Discovery

Gathers facts: Error logs, user reports, reproduction steps.

/debug Login returns 403 even with correct credentials

Hypothesis

Formulates potential causes prioritized by likelihood.

Verification

Systematically tests each hypothesis using scripts or logs.

Resolution

Implements the fix and adds a regression test.

Example Session

User: /debug Form submission fails silently

Agent: Phase 1: Discovery

Reading CheckoutForm.tsx... Found handleSubmit. ERROR: Cannot read properties of undefined

Agent: Phase 2: Hypothesis

emailRef.current is null on mount
Event handler not bound correctly

Agent: Phase 4: Resolution

Fix applied: Added null check to emailRef. ✅ Test passed: Form submits successfully.

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

Try /debug on an existing bug
See Deployment to ship your fix