AI Debugging: The 3-Context Framework
AI is a hypothesis generator, not a fix button. The speed of resolution is directly proportional to the quality of the 'crime scene' you provide. This framework turns vague errors into surgical fixes by providing the three missing pieces every model needs.
Traditional debugging is a solo investigation. AI-assisted debugging is a partnership: you are the detective who understands the case context; the AI is the pattern-matcher who scans every known failure at machine speed.
The Investigation Standards: Fix Button vs. Investigation Partner
Don't send "my code is broken." Send evidence. The difference between a 5-minute fix and a 40-minute struggle is the quality of your framing.
Framing Comparison
- "I have a TypeError."
- "Here's 200 lines of component code."
- "It doesn't work. Fix it."
- Result: Generic guesses and circular logic.
- Full error message + Stack trace.
- Relevant file references (@OrderHistory.tsx).
- Expected vs. Actual behavior clearly stated.
- Result: Surgical fix targeting the root cause.
The 3-Context Framework: The Evidence Pack
These three pieces of evidence are non-negotiable for a fast resolution.
The Essential Contexts
Paste the entire error message. Never truncate; the root cause often hides in the deep call chain of third-party libraries.
Reference the specific files in the call chain. AI needs to see the failing code AND the parent code that passed the bad data.
Expected vs. Actual. AI doesn't know what it's supposed to do—intent is the final piece of the puzzle that stops hallucinations.
The Master Debugging Prompt Template
Use this template to save 30 minutes of circular prompting.
# BUG REPORT
# 1. THE CRIME SCENE
[Paste Full Stack Trace / Error Message Here]
# 2. THE RELEVANT FILES
Files: @api/orders.ts, @components/OrderCard.tsx
# 3. INTENT vs. REALITY
- EXPECTED: When I click 'Refund', the status should change to 'Processing' immediately.
- ACTUAL: The UI hangs for 2 seconds, then throws the 500 error above.
# 4. RECENT CHANGES
I recently updated the 'Stripe' SDK to v4.0.
# TASK
Analyze the stack trace. Explain the root cause. Propose a surgical fix.
Advanced Pattern: AI-Guided Strategic Logging
When a bug is intermittent or "silent" (no error, just wrong data), stop asking for fixes and start asking for Eyes.
- Prompt: "Don't fix the code yet. Add strategic logging to trace the
order_totalvariable from the API response all the way to the UI render. Identify where the data shape changes." - Result: The AI identifies that a 'string' was passed instead of a 'number', causing a math failure downstream.
Case Study: The Silent Hydration Error
Hydration Fixes
Developer asks for a fix. AI suggests 5 different ways to wrap the component in useEffect. None work.
Developer provides the exact warning: "Text content did not match." AI immediately identifies a new Date() being called on the server vs client. Fix takes 30 seconds.
Key Takeaways
Framing the problem correctly saves 30 minutes of frustration. Be the Detective, let AI be the Search Engine.
If the AI can't explain the root cause clearly, it's guessing. Clarify the explanation before you ever copy a line of code.
AI is world-class at matching actual behavior, but only you can define the intended behavior. Explicitly state the difference to get accurate results.