CS 319 · Meeting 4 of 10
Spec-driven development as a gated pipeline — and the foreman's signature deliverable.
Agenda · 100 min
Reading: chapters 8–9
Core concept · ch 8
each arrow is a markdown artifact · each gate is a human decision (GitHub Spec Kit · BMAD · the field consensus)
The human's job at each gate
Verification and critique — not passive approval. Ask: what did the phase miss? What is ambiguous? What would I test?
The phase teams skip
Specify. It feels slow, and skipping it feels efficient — right up until Plan invents requirements and Implement ships them confidently.
Core concept · ch 9
1 · PRD
What and why, for humans. The only doc a stakeholder reads end-to-end.
2 · System Architecture
Services, boundaries, dataflow. Where the council debates live.
3 · API Contracts
Endpoints, schemas, errors. The most load-bearing doc — skip it and every downstream team breaks.
4 · Database Schema
Tables, migrations, constraints. Changes ripple through API + tasks.
5 · UI Structure
Screens, states, empty/error cases. What the user actually experiences.
6 · Task Breakdown
The ordered, agent-sized work items everything above compiles down to.
Cross-referenced: change the schema → the API contract changes → the tasks change. The six docs are one artifact with six views. They are the proof a council did its job.
Example · one feature, six views (condensed)
PRD merchants can request refunds for paid invoices ≤ 30 days old
ARCHITECTURE new service refunds, talks to invoicing + payments, async via queue
API POST /refunds · GET /refunds/{id} · webhook refund.status_changed
400 bad_request · 409 already_refunded · 422 window_expired
SCHEMA refunds(id, invoice_id, amount, status[pending|approved|paid|rejected],
reason, created_at) + status_history(refund_id, from, to, at, actor)
UI RequestRefundScreen: amount prefilled, ≤ validation live,
states: idle / confirming / submitted / done | error(window)
TASKS 1 migrations 2 service core 3 endpoints 4 webhook 5 UI 6 e2e tests
Sixty minutes total, by one foreman + a council. Not perfect — cross-referenced and honest. Note how the API errors (409, 422) already encode the PRD's 30-day rule.
The failure mode · ch 9
Run the change-impact thought experiment: delete each doc the night before implementation.
Rule: the contract is the doc you never skip. It is also the one your verifier can check mechanically (schema validation).
Case study · part 4 of 10
Their first run of the full workflow (Describe → Council Debates → Consensus → Execute) on the refund feature. Council of four (PM, Architect, Backend, Data) produced the six documents in one evening session.
Then the verifier earned its keep: the Data specialist's schema had amount as integer rupiah; the Backend lead's contract said decimal. Deterministic schema check caught it — a mismatch that would have surfaced as a production rounding bug in a currency field. Zero vibes were involved.
Team quote for the retro: "The documents argued so we didn't have to."
Doc sprint · 25 minutes · in class
Your feature
"Group-split: share one invoice between multiple payers."
Steps
Debrief: who picked the API contract? Defend your two picks in one sentence each.
Assignment A4 · due before Meeting 5
Task
Take a greenfield idea (side project, student org tool, or extend Kirana). Produce all six documents — one hour each, hard cap. Agents may type; you review every line.
Deliverables
Six docs (they may be short — they must cross-reference) · a cross-reference map (which doc changes when each other doc changes) · a hole-hunt: one contradiction found and fixed, documented.
Rubric
Cross-reference integrity 40% · API contract rigor 25% · honesty of the time log 15% · hole-hunt 20%.
Next: orchestration patterns and the verifier discipline — how loops know when to stop. Read ch 10–11.