تجاوز إلى المحتوى
جرّب المرجع الدورة المحفوظات
العربية
← كل playbooks Engineering

playbook

Trace a bug to its root cause and prove the fix

Hand Claude the full stack trace and the failing input, get a ranked list of likely causes with file:line pointers, then a fix plus a test that fails on the old code and passes on the new.

متوسّط ~30 min

متى تلجأ إلى هذا

Users report they get logged out at random. There's a stack trace, a request that triggers it, and a dozen plausible suspects. The trap is to start patching the first thing that looks wrong. This system makes you debug from *evidence* — diagnosis first, ranked by likelihood, then a fix you can prove with a test instead of a hopeful "that should do it."

جهّز هذا أولًا

  • The **full** stack trace, verbatim — every frame, not "it crashes on login." The exact frames are usually where the answer is.
  • The request, input, or steps that reproduce it — the smaller and more exact, the better.
  • The repo open in the project root, so Claude can read the actual files the trace points to.

الـ workflow

  1. Diagnose before you patch — and rank the causes

    Force a hypothesis list before any code changes. You want to sanity-check the reasoning while it's cheap prose, not after it's a 200-line diff.

    أنت تطلب 
    Here's the full stack trace and the request that triggered it. Trace the logic end to end and give me the three most likely root causes, ranked, with the file and line for each and the reasoning. Don't fix anything yet.

    ما تحصل عليه A ranked list with auth/session.ts:142-style pointers and the why behind each — a stale TTL, a race on token refresh, a clock-skew check — so you're debugging from evidence, not vibes.

    "Don't fix anything yet" is doing real work here. The diagnosis is the part you most need to check with your own judgment.

  2. Confirm the real cause against the code

    Pick the hypothesis that fits and make Claude prove it's the one — by pointing at the exact code path, not by asserting it.

    أنت تطلب 
    Cause #2 looks right. Show me the exact code path that produces this bug — the lines that set the bad state and the lines that read it — and explain why the current behaviour is wrong.

    ما تحصل عليه A concrete walk from cause to symptom across the real files, so you understand the bug, not just the patch you're about to approve.

  3. Fix it, and write the failing test first

    A change without a test it turned green is a guess. Ask for the regression test that reproduces the bug, then the smallest fix that flips it.

    أنت تطلب 
    Now add a test that fails on the current behaviour and passes once it's fixed, then make the smallest change that fixes it. Show me the diff before you touch anything else.

    ما تحصل عليه A failing-then-passing regression test plus a tight diff. The red-to-green test is the receipt that the fix addresses the *bug*, not just the symptom you described.

  4. Run the real loop and read the diff

    Let it run your actual suite and type-checker, feed back any red, and read every line before you approve. You're still the author of record.

    أنت تطلب 
    Run the full test suite and the type-checker. If anything's red, fix it and show me what changed. Then give me the final diff to review.

    ما تحصل عليه A green suite and a reviewed diff — usually right, occasionally confidently wrong, which is exactly why you read it.

اجعله ملكك

  • **No reproduction yet:** start with "write the smallest script or test that reproduces this from the trace" — once it reproduces, the rest of the system applies.
  • **Heisenbug:** ask it to add targeted logging around the ranked suspects, run again, and reason from the new output rather than guessing in the dark.

انتبه إلى

  • Paste the trace and input **verbatim** — don't summarize. "It crashes on login" throws away the exact frame that holds the answer.
  • Make it prove the fix with a failing-then-passing test. A confident explanation with no red test it turned green is still a guess.
  • Read the diff before you approve it. Treat its output like a PR from a fast, eager junior — usually right, occasionally wrong with total confidence.

ستحصل في النهاية على You go from a random-looking bug to a root cause you understand and a fix backed by a regression test — debugged from evidence in an afternoon, not guessed at over two days.