Sessions 11 & 12 — Review, Showcase & Close

The Day-2 close

S11: does the running code actually match the spec? Find the drift, decide what to do.
S12: ship it live, then commit to one concrete change you'll make Monday.

SESSION 11 — Code Review & Spec Drift (45 min)

Part 1 · What is spec drift? (7 min)

Spec drift is when generated code passes all the tests you have
but quietly violates a requirement you have —
because you wrote the tests against the code, not the spec.

Two concrete examples:

  • Spec says GET /entries sorts by timestamp DESC. The agent sorted by id. The endpoint works; your test passes (you tested the endpoint, not the requirement). You never notice.
  • Spec says SearchBar has a 300ms debounce. The agent skipped it. Search still works — it just hammers the API on every keystroke. No test catches a missing timing behaviour.

Spec drift is not a model failure — it's a review failure.
The model generated reasonable code; you accepted it without checking it against the spec.
That's the gap this session closes.

Tests vs Evals — How AI Output Gets Verified

"Generation is solved. Verification is the new craft." — Addy Osmani

Two complementary checks — mature teams run both:

  • Tests verify the deterministic parts: this input → that output. Run by code, in CI. (your INVEST acceptance criteria → assertions)
  • Evals verify the non-deterministic parts: did the agent take the right trajectory, choose the right tools, hit the quality bar? Scored by rubrics, labelled sets, or an LM-as-judge.

Tests check the output; evals also check the path taken to get there.
Spec drift is the cheap, human version of an eval — bmad-code-review grading code against this spec. Without tests and evals, it's still vibe coding.

Part 2 · Class review — live diff against spec (20 min)

Step 1 — Load the Reviewer (V6 bmad-code-review)

In BMAD V6, review is the bmad-code-review workflow (Developer agent, Amelia — trigger CR). Its job is to compare, not create. It reports spec violations with precision; it does not refactor, restyle, or add features.

For each deviation it should state: the spec § violated, what the spec requires, what the code does instead, a severity (BLOCKER = breaks a stated requirement · WARNING = weakens an NFR), and a decision: FIX CODE or UPDATE SPEC.

Step 2 — Review one real diff on the projector

Pick a real student commit (real drift teaches 10× better than a manufactured example). Get the diff two ways:

  • Editor: Source Control panel → click a changed file → split diff view.
  • Terminal: git diff HEAD~1 -- backend/src/routes/entries.ts

Then run the review with the spec section in context:

=== SPEC SECTION ===
[paste the relevant section from docs/spec.md — §2 routes, §1 components, §3 schema]
=== CODE DIFF ===
[paste the git diff]
=== REVIEW REQUEST ===
Review this diff against the spec section. List every deviation:
spec §, required, actual, severity (BLOCKER|WARNING), decision (FIX CODE|UPDATE SPEC).

Step 3 — The FIX CODE vs UPDATE SPEC decision

The heart of the session. For each deviation:

Deviation FIX CODE (spec is truth) UPDATE SPEC (requirement changed)
Tags handled as array, spec says comma-separated TEXT .split(',') — model drifted only if the team decides the schema must become TEXT[] (→ migration + every endpoint)
WeeklySummary groups dates differently than specified spec defines it; fix the code only if the defined grouping is genuinely wrong/worse UX → update spec first
GET /entries searches when no tag given spec says optional filter; fix only if the PRD changes to "default = search" (a product change)
Agent adds DELETE /entries (not in spec) out of scope; remove it never silently — update PRD out-of-scope → spec → stories first
SearchBar debounce 500ms, spec says 300ms fix; it's a stated requirement only with a user-tested reason; update spec first
Search misses the <200ms NFR fix (index/optimise) — an NFR is a requirement only if genuinely unachievable on target HW → justified relaxed target

The one governing principle:
Update the spec when a requirement genuinely changed — the real world taught you something the spec didn't know. Fix the code when the model made a wrong assumption or ignored a stated constraint.
Heuristic: if you'd need to update the PRD to justify it, it's a real requirement change. If the PRD is still valid, the code is wrong.

Part 3 · Structured self-review (13 min)

Step 4 — Students review their own ≥3 commits

For each recent commit: open the diff → read the spec § from the commit message → copy that spec section → run bmad-code-review with spec + diff → for each DEVIATION, decide FIX CODE or UPDATE SPEC → record it in a new docs/drift-log.md.

Students with no deviations: run the review on the finale code (App.tsx / WeeklySummary / the seed) — those drift most.

✅ Checkpoint: every student ran the review on ≥3 commits · every deviation has a recorded decision · docs/drift-log.md exists with ≥1 entry.
Ask: "Who found a BLOCKER in their own code?" then "Who made an UPDATE SPEC call — what changed and why?" (the most valuable discussion).

Part 4 · The pre-commit review template (5 min)

Step 5 — The takeaway artifact: docs/review-prompt.md

This is what students actually keep. Create it:

# Pre-commit Review Checklist
## Use before every commit that touches spec-covered code

### 1 — Identify the spec section
Commit message: [your message]
Spec section:   [the §ref from it]

### 2 — Run bmad-code-review (Reviewer) with:
=== SPEC SECTION ===   [paste §N from docs/spec.md]
=== CODE DIFF ===      [git diff HEAD -- path/to/file]
=== REVIEW REQUEST === list deviations: §, required, actual, severity, FIX CODE|UPDATE SPEC

### 3 — Act
- BLOCKER  → do not commit; fix code or update spec first
- WARNING  → commit with note: "KNOWN DRIFT: … — tracked in drift-log.md"
- none     → commit normally

### Decision rule
FIX CODE: spec still valid, model assumed wrong.
UPDATE SPEC: real requirement change — PRD first, then spec, then code.

Step 5 — commit the artifact (cont.)

Commit it:

git add docs/drift-log.md docs/review-prompt.md
git commit -m "session11: drift log and pre-commit review template"
git push origin main

S11 done when both files are on GitHub, and every student can run the review, read the DEVIATION output, and make the FIX/UPDATE call with reasoning.

SESSION 12 — Showcase + "Next Monday" (30 min)

Part 1 · Live showcase (25 min)

Step 6 — Format: 4 minutes per team, exactly

  • 0:30 — "Here's the spec section that governs this feature." (docs/spec.md open)
  • 1:00 — Live in the agent: send a prompt that creates a StackLog entry via the MCP server. Show the tool calls.
  • 1:00 — Switch to the browser (localhost:3000). Refresh. The new entry appears. Demo search/tags if working.
  • 0:30 — Show one GitHub commit with a spec-referenced message.
  • 1:00 — One audience question. Timer stops.

Session 12 · showcase (cont.)

🔗 The integration moment — call it out every time:
"That entry was created by the MCP server from Day 1. It just appeared in the React app from Day 2. Same data — written yesterday, displayed today."

💡 The MCP-dashboard finale (optional, high-impact): for the strongest close, open the MCP-client dashboard (the verified mcp-dashboard) alongside the app. The agent creates an entry → both the React app and the dashboard show it — because both are clients of the same MCP server. This is the sharpest possible demonstration of "MCP is a universal interface, not AI-only."

If a team's app isn't running — don't skip them. Show the spec + GitHub repo. The artifacts are still valid.

Step 7 — Audience questions (ask the audience, not the presenter)

  • "What spec section did that feature satisfy? Find it in the spec."
  • "To add tag autocomplete tomorrow — what changes first, spec or code?"
  • "Where did the most drift happen — spec, stories, tasks, or code?"
  • "What one thing in the spec would you write differently now you've seen it run?"

Part 2 · "Next Monday" + close (5 min)

Step 8 — The "Next Monday" card (the named takeaway)

Laptops closed. 60 seconds. Write one sentence by hand:

"Starting Monday, the ONE change I'll make to how I develop software is: ___"

Rules for a valid answer: a specific action, not a feeling · doable alone, not requiring the whole team · achievable Monday, not a 3-month transformation.

Valid examples:

  • "Write a one-page PRD before starting any new feature — even a tiny one."
  • "Run the pre-commit review prompt before every commit that touches business logic."
  • "Define success metrics before writing code — not after."
  • "Build a custom MCP server for the data source I work with most."

Ask 3–4 to read theirs aloud; write them on the board.

Step 9 — Closing

"In two days you went from using AI as a question-answering machine to building and designing AI systems."

"Day 1: you built an MCP server, connected it to a multi-tool agent pipeline, intentionally broke it, and documented exactly why it failed and how to fix it."

"Day 2: you wrote a spec that constrained everything after it — stories from the spec, tasks from the stories, code from the tasks — then reviewed the code against the spec and made principled decisions."

"The app running on localhost:3000 was not vibe-coded. Every component references a spec section. Every endpoint has a story. Every commit names the requirement it satisfies."

"That's what it is to be an AI Architect rather than an AI user. That's what you leave as."

(then) "Push everything to GitHub before you leave — the MCP server, spec, stories, tasks, app, drift log, review prompt. That repo is your portfolio artifact. Someone will look at it."

Step 10 — Resource handoff

Resource What it is Where
BMAD Method (V6) the spec-driven framework used all of Day 2 docs.bmad-method.org · github.com/bmad-code-org/BMAD-METHOD
MCP servers (official) pre-built servers — Filesystem & 20+ github.com/modelcontextprotocol/servers
MCP TypeScript SDK the SDK behind the Lab 2 StackLog server github.com/modelcontextprotocol/typescript-sdk
DuckDuckGo MCP server the keyless search server from Lab 1 nickclyde/duckduckgo-mcp-server
Building effective agents the agentic-pattern guide (ReAct/Plan/Reflection) anthropic.com/research/building-effective-agents
Google Antigravity the agent-first IDE used throughout the workshop delivery environment
MCP Inspector debug MCP servers — browse schemas, fire calls npx @modelcontextprotocol/inspector
Spec Kit GitHub's SDD toolkit (canonical vocabulary) github.com/github/spec-kit
better-sqlite3 the synchronous SQLite driver from Lab 6 github.com/WiseLibs/better-sqlite3

⚠️ Reconciled from the printed guide: it lists Brave Search, Continue, and Ollama — our delivery uses DuckDuckGo (keyless) for search and Antigravity as the host. Continue/Ollama are fine optional extras but aren't our stack.

Step 11 — Final push

git status        # want: "nothing to commit, working tree clean"
# if not:
git add . ; git commit -m "workshop complete: full StackLog capstone" ; git push origin main

What every student leaves with

On GitHub: stacklog-mcp/ (Lab 2) · lab3-system-prompt.md + lab3-retro.md (Lab 3) · docs/spec.md (Lab 4) · docs/stories.md + docs/tasks.md (Lab 5) · backend/ + frontend/ (Lab 6) · docs/drift-log.md + docs/review-prompt.md (S11).

Three things:

  • Technical artifacts — a real full-stack AI-powered app on GitHub.
  • A mental model — agents as designed systems, not magic; specs as constraints, not documentation.
  • One concrete Monday action — written by hand, readable right now.

Day 1 built the tools the AI uses. Day 2 specced and built the app that displays them.
One prompt, two days, one live system. That's the workshop.