Debug Code with AI

How It Works

Paste the error message, stack trace, the code around the problem, language, and any context (what you were trying to do, recent changes). The workflow gives you a numbered debugging process, exact prompts to feed the AI at each stage, common patterns for your language, how to verify the fix, and a review checklist so the AI helps without introducing new bugs.

What to Provide

Debug Workflow Blueprint

This is the finished deliverable.

1. Structured Debugging Method (Always Follow This Order)

1. Reproduce the bug locally with the smallest possible input or test case.

<blank line between>

1. Isolate: Narrow to the exact function, file, or line where the failure occurs.

<blank line between>

1. Hypothesize: Form 1–3 possible root causes based on the symptoms and recent changes.

<blank line between>

1. Test the hypothesis with the AI (targeted prompts below) or by adding logs / minimal repro.

<blank line between>

1. Apply the fix in the smallest possible change.

<blank line between>

1. Verify: Run the original reproduction + broader tests + any new regression test.

<blank line between>

1. Root cause vs symptom: Document why it happened so it does not recur.

2. Ready-to-Use Prompts

Prompt 1: Reproduce and isolate

"Here is the error:

[[full error + stack trace]]

Here is the relevant code:

[[paste the function or file, mark the lines mentioned in the stack]]

What I was trying to do: [[context]]

Help me create a minimal reproduction case. Then point to the smallest section of code most likely responsible."

Prompt 2: Hypothesis + explanation

"Explain the root cause in one or two sentences. Then list the 2–3 most likely hypotheses ranked by probability. For each, give a one-line test that would confirm or disprove it."

Prompt 3: Fix (only after hypothesis)

"Propose the smallest code change that fixes the root cause.

Rules:
- Do not change unrelated code.
- Preserve existing behavior for other cases.
- Include comments explaining the fix.
- After the code, list what tests or checks I should run.

Language: [[language + version]]
Style: [[follow our conventions or link to rules]]"

Prompt 4: Regression test

"Write a minimal test (unit or integration) that would have caught this bug.

Framework: [[Vitest / Jest / pytest / etc.]]

Place it next to the source file per our convention."

Prompt 5: Review the AI suggestion (always run this)

"Review this proposed fix for correctness, performance, security, and style:

[[paste the diff or changed code]]

List any issues or risks. Suggest improvements or a safer alternative if one exists."

3. Language-Specific Common Patterns (Quick Reference)

Python:

• Indentation or import order issues after refactors.
• Async / await mismatches or missing await.
• None vs empty list/string confusion.
• Dependency version skew (especially with pydantic, fastapi, sqlalchemy).
• Path or encoding problems on different OS.

TypeScript / JavaScript (Node or browser):

• Undefined / null at runtime vs type says otherwise.
• Async timing (forgotten promises, race conditions).
• Module resolution or import type vs value.
• Event listener leaks or stale closures in React.
• Wrong assumption about what the framework provides (Next.js, etc.).

React / Frontend:

• State not updating because setState is async or key prop missing.
• Effect dependency array problems.
• Props drilling or context value changing identity every render.
• Hydration mismatch (SSR vs client).

General:

• Off-by-one, wrong variable, copy-paste error, config/env var missing.
• Recent dependency upgrade that changed behavior silently.

When the AI suggests something, ask it "what is the most common cause of this symptom in [[language]]?" and cross-check.

4. Verification Habits (Non-Negotiable)

1. Run the exact reproduction that was failing before the fix.

<blank line between>

1. Run the project's full test suite or relevant test command.

<blank line between>

1. Type check / lint if applicable.

<blank line between>

1. Manual smoke of the user flow if it is user-facing.

<blank line between>

1. Add or update a test that would catch regression.

<blank line between>

1. Read every line of the change yourself. Understand it.

If any step fails, do not commit. Go back to hypothesis.

5. How to Talk to the AI Without Getting Bad Fixes

• Give the full error + stack + surrounding code.
• State what "correct" looks like.
• Ask for smallest change + explanation.
• Always have it review its own suggestion.
• When it gives a big rewrite, ask for a diff against the original instead.
• Never paste secrets, tokens, or customer data.

6. 10-Minute Debug Session Template (When You're Stuck Fast)

1. Paste error + code + "Give me a minimal repro and top 2 hypotheses."
2. Run the suggested repro or add 2 print/log lines.
3. "Based on this output, which hypothesis is correct? Smallest fix?"
4. Apply, run tests, review.
5. Commit with message that includes the root cause.

Worked Examples

Example 1: Python FastAPI 422 Validation Error

Error: 422 on POST with Pydantic model after adding a new field.

Process: Isolated to model, hypothesis = field default + required mismatch after refactor.

Fix: Made field Optional with default or used Field(...).

Verification: Ran the exact curl that failed + pytest for the endpoint + manual.

Example 2: React useEffect Infinite Loop

Symptom: Component re-renders forever after adding a new dependency.

Process: AI pointed to object created inside component passed as dep.

Fix: useMemo or useCallback + correct deps.

Added test: Component test that asserts no excessive renders.

Example 3: Node async timing bug in queue processor

Error: Jobs marked complete before work finished; occasional duplicate work.

Process: Added logs, hypothesis = missing await on async handler.

Fix: Await the processor + proper error handling + retry with backoff.

Result: No more duplicates in 10k job test run.

Format Checklist

After the Fix

Write one sentence in a comment or commit: "Root cause: [[one line]]. Fixed by [[change]]. Test added: [[name]]."

This turns every bug into a small lesson and makes the next similar bug 10x faster to spot.

Use the prompts and order every time. You will debug faster and introduce fewer new problems.