Section 7 · Lesson 1
Spec-First Debugging — Evidence, Not Guesswork
Leave ‘I think’ behind — the spec is your case file, MCP is your detective badge, Playwright reenacts the scene, DevTools gathers forensics, and the runbook closes the case.
"I know — and here is the proof.
Stop guessing — debug like a detective
Runtime errors that vanish when you look, random performance tips that make no sense — bugs feel like unsolved mysteries. Replace “I think the problem might be here” with a repeatable procedure backed by cold, hard evidence.
Guesswork vs evidence
The old way: gut feelings, chaos, bugs you cannot reproduce. The new way: systematic, repeatable diagnostics — the difference between “I think” and “I know, and here is the proof.”
The case file is the spec
Before code or logs, open requirements.md — the single source of truth for what should have happened. You cannot know something went wrong until “right” is defined without ambiguity.
Clues in a good spec
Concrete, measurable facts: exact user journeys, hard performance budgets (e.g. LCP under 2.5 seconds), and acceptance criteria you can observe in a live system — not vague ideas.
Detective + forensics kit
Lead investigator: an AI agent working through MCP — clearance to observe the live system, not guess from static code. Playwright reenacts the user journey from the spec. Chrome DevTools is the lab — traces, main-thread blockers, runtime evidence.
Six-step runbook
A standard playbook so every investigation is thorough: review spec → reenact with Playwright → capture DevTools trace → analyze root cause → map findings to the spec → update the spec with what you learned.
Bugs make the system smarter
Incident → investigate → fix → update the spec with stricter budgets or new rules → automated checks prevent that class of bug from returning. Compounding value — not just patching holes.
Opportunities, not failures
Every bug can permanently strengthen the system against a whole category of issues. What if each fix made your application smarter and more resilient?
Old way
Chaotic debugging — reproduce-if-you’re-lucky, opinions, static code reading without live proof.
Evidence-driven
Spec-first, MCP-observed, trace-backed — repeatable runs that build an undeniable case.
Clues in the spec (case file)
- ▸Documented user journeys — steps the agent must reenact in Playwright
- ▸Performance budgets — e.g. Largest Contentful Paint (LCP) under 2.5s
- ▸Observable acceptance criteria — what “correct” looks like in production-like conditions
Detective & forensics kit
Agent badge
Secure protocol — bounded clearance to observe the live system, not infer from snippets.
Scene reenactment
Replay the spec’s user journey on command until the bug appears reliably.
Forensics lab
Performance traces, main-thread long tasks, forced reflow flags — evidence for the case file.
Six-step runbook
Standard procedure every time — no “maybe it is this” debugging.
- 1
Review the case file
Read the spec — budgets, journeys, acceptance criteria
- 2
Reenact the scene
Playwright MCP — reproduce the user journey from the spec
- 3
Gather forensics
Chrome DevTools MCP — capture performance trace while journey runs
- 4
Analyze clues
Find root cause in the trace (long tasks, reflow, failed requests)
- 5
Build the case
Link evidence to what the spec said should happen
- 6
Update the record
Revise requirements.md — tighter budgets, new rules, learned constraints
Runtime Gateflow
A repeatable diagnostic loop inside spec-driven development — from a requirement to evidence, root cause, and a verifiable fix.
requirements.md / SPEC
Select spec
Pick a specific requirement to verify — one acceptance criterion or user journey, not the whole backlog.
Loop: evidence anchors back to requirements.md — vague specs surface in the trail.
Case studies
Case 1 — LCP regression
Key page feels slow; users notice; violates the performance budget in the spec.
- Spec fact
- LCP must be under 2.5 seconds.
- Evidence
- DevTools trace shows LCP at 4.1 seconds — clear violation.
- Root cause
- Long task blocking the main thread — inefficient script prevents timely render.
Case closed with proof — no guesswork.
Case 2 — Janky animation
Animation should be smooth but stutters and hesitates.
- Spec fact
- Smooth motion per acceptance criteria — no layout thrashing.
- Evidence
- Performance panel shows purple forced-reflow markers; trace shows a loop mutating style then reading height repeatedly.
- Root cause
- Classic layout thrashing — read/write layout in a tight loop.
Smoking gun in the trace — case closed.
Spec feedback loop
- Incident observed against spec expectations
- Agent runs spec-first runbook with MCP + Playwright + DevTools
- Fix applied with traceability to requirements
- Spec updated — stricter budget or new invariant
- CI and agents enforce the updated spec — class of bug prevented
Practice
Check your understanding
A few minutes of recall now saves rereading later.
1.What is the first step of a spec-first debugging session?
2.LCP measures 4.1 s against a 2.5 s budget. What gives you the root cause?
3.Which pattern causes forced reflow?
4.After the fix is verified, what closes the loop?
Order the spec-first debugging runbook. Use the arrows to move a step, then check your order.
- 1Build the case
- 2Gather forensics
- 3Reenact the scene
- 4Analyze clues
- 5Review the case file
- 6Update the record