SDCourse overview

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
Living requirements.md →

Detective & forensics kit

MCP

Agent badge

Secure protocol — bounded clearance to observe the live system, not infer from snippets.

Playwright MCP

Scene reenactment

Replay the spec’s user journey on command until the bug appears reliably.

Chrome DevTools MCP

Forensics lab

Performance traces, main-thread long tasks, forced reflow flags — evidence for the case file.

Loading MCP bridge…

Six-step runbook

Standard procedure every time — no “maybe it is this” debugging.

  1. 1

    Review the case file

    Read the spec — budgets, journeys, acceptance criteria

  2. 2

    Reenact the scene

    Playwright MCP — reproduce the user journey from the spec

  3. 3

    Gather forensics

    Chrome DevTools MCP — capture performance trace while journey runs

  4. 4

    Analyze clues

    Find root cause in the trace (long tasks, reflow, failed requests)

  5. 5

    Build the case

    Link evidence to what the spec said should happen

  6. 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

  1. Incident observed against spec expectations
  2. Agent runs spec-first runbook with MCP + Playwright + DevTools
  3. Fix applied with traceability to requirements
  4. Spec updated — stricter budget or new invariant
  5. CI and agents enforce the updated spec — class of bug prevented
Living specs (Section 6 · Lesson 1) →

Practice

Check your understanding

A few minutes of recall now saves rereading later.

0 of 4 answered
  1. 1.What is the first step of a spec-first debugging session?

  2. 2.LCP measures 4.1 s against a 2.5 s budget. What gives you the root cause?

  3. 3.Which pattern causes forced reflow?

  4. 4.After the fix is verified, what closes the loop?