Definition of Done - Spec-First Build
What this is: the bar your work has to clear to count as done - not “it runs on my machine”, but specified, contracted, tested, reviewed, and signed. Every item cites the real corporate-standards ID it comes from, so this sheet is three things at once: a gate during the session, a grading sheet for facilitators, and a takeaway you keep for Monday.
It is the practical form of The 5 Ways We Work With AI. Print one per person.
How to read it:
- MUST items gate the merge. Miss one and the work is not done - it cannot pass Gate 2 and cannot be scored as shipped.
- SHOULD items are quality points: they raise your score and they’re what “good” looks like.
- The arc this enforces: spec → contract → code → six-layer tests → human review. Tick top to bottom.
| MUST | gates merge | non-negotiable |
| SHOULD | earns points | what “good” looks like |
Contract - the machine-readable agreement
| ✓ | Item | Level | Cite |
|---|---|---|---|
| ☐ | The endpoint has a machine-readable OpenAPI definition (the contract is a file, not a conversation). | MUST | REQ-API-2 |
| ☐ | The contract is kept in sync with the implementation - the response the code returns matches the schema exactly. | MUST | REQ-API-2 |
| ☐ | The /recommend 200 response is a real $ref to a defined schema (RecommendResponse), not a TODO, and was frozen at Gate 1. | MUST | REQ-API-2, REQ-API-5 |
| ☐ | Errors use the shared error envelope (RFC 7807 Problem / problem+json), not ad-hoc shapes. | MUST | REQ-API-5 |
| ☐ | Explicit versioning is present and governed (info.version; version belongs in the path for a real service). | MUST | REQ-API-4 |
| ☐ | Schemas are reused, not copied - Lesson / DimensionScore are $ref-ed, consistent conventions throughout. | SHOULD | REQ-API-5 |
| ☐ | The API is treated as a product - named, summarised, with examples a consumer could build against. | SHOULD | REQ-API-1, REQ-API-3 |
Spec - describe before you generate
| ✓ | Item | Level | Cite |
|---|---|---|---|
| ☐ | Acceptance criteria written before any feature code (defects prevented at inception, not caught after). | MUST | QUAL-PRINC-SHIFT-LEFT |
| ☐ | An ADR captures the decision and, crucially, the why - the trade-off, not just the choice. | MUST | ENG-PRIN-DOC-STMT |
| ☐ | The ADR includes idempotency reasoning: why GET is safe/idempotent here, and what would change (an Idempotency-Key) if it became a write. | MUST | REQ-API-6 |
| ☐ | The solution is the simplest thing that meets the contract - no speculative abstractions (KISS / YAGNI). | SHOULD | ENG-PRIN-SIMPLE-STMT |
| ☐ | The decision is durable - the ADR will outlive the chat it was made in, and lives where the team can find it. | SHOULD | ENG-PRIN-DOC-STMT |
Implementation - small steps, on trunk
| ✓ | Item | Level | Cite |
|---|---|---|---|
| ☐ | The endpoint fulfils the frozen contract - it actually returns the agreed shape for the happy path. | MUST | REQ-API-2 |
| ☐ | Work landed as small, reviewable commits, not one mega-change. | MUST | ENG-PRIN-INCR-STMT |
| ☐ | The first commit was stub + a failing contract test (red), then the implementation drove it green. | MUST | ENG-PRIN-INCR-STMT, QTEST-CONTRACT |
| ☐ | Code is clean and self-explanatory - readable names, no dead code, no commented-out experiments. | SHOULD | ENG-PRIN-CLEAN-STMT |
| ☐ | Branch was short-lived and integrated to trunk frequently (no long-running fork). | SHOULD | ENG-PRIN-TRUNK-STMT |
| ☐ | It builds and the suite passes locally before push - green on your machine first. | SHOULD | ENG-PRIN-LOCAL-STMT, ENG-PRIN-CI-STMT |
Tests - test at the lowest viable layer, no duplication
| ✓ | Item | Level | Cite |
|---|---|---|---|
| ☐ | A contract test asserts the response matches the OpenAPI schema. | MUST | REQ-API-7, QTEST-CONTRACT |
| ☐ | Each behaviour is tested at the lowest viable layer - pure logic as a unit test, not pushed up to E2E. | MUST | QTEST-EARLY, QUAL-PRINC-AUTOMATION |
| ☐ | No duplicated coverage - the same rule isn’t asserted at three layers; each layer earns its place. | MUST | QTEST-NO-DUP, QUAL-PRINC-WASTE |
| ☐ | The pyramid is right-shaped: many unit, some component/contract, few system/E2E. | SHOULD | QTEST-UNIT, QTEST-COMPONENT, QTEST-SYSTEM, QTEST-E2E |
| ☐ | Quality was shifted left (fast tests catch it early) and shifted right is considered (what you’d monitor in prod). | SHOULD | QUAL-PRINC-SHIFT-LEFT, QUAL-PRINC-SHIFT-RIGHT |
| ☐ | Any remaining manual checks are deliberate, named, and minimal - not the default. | SHOULD | QTEST-MANUAL |
UX - every state has a design
| ✓ | Item | Level | Cite |
|---|---|---|---|
| ☐ | The UI handles the core states: loading, empty, error, and populated. | MUST | QUAL-PRINC-SDLC |
| ☐ | The error state consumes the contract’s error envelope - the UI reads Problem, it doesn’t invent its own. | SHOULD | REQ-API-5 |
| ☐ | Edge / boundary states are designed (e.g. user with N/A dimensions, fewer than 5 recommendations). | SHOULD | QUAL-PRINC-SDLC |
Review - a human always signs the work
| ✓ | Item | Level | Cite |
|---|---|---|---|
| ☐ | Approved by a named non-author human, reviewed against this DoD. AI may assist the review; AI may not approve. No self-merge. | MUST | ENG-PRIN-REVIEW-STMT |
| ☐ | An owner is named - You Build It, You Own It - accountable for what shipped. | MUST | ENG-PRIN-OWN-STMT |
| ☐ | The merge respects the team’s Definition of Done as the shared SDLC bar (this sheet). | MUST | QUAL-PRINC-SDLC |
| ☐ | Cross-role handoff is real and visible: the build used Product’s criteria, Architecture’s ADR, QA’s tests - quality is a team property, not one person’s. | SHOULD | QUAL-PRINC-TEAM |
| ☐ | If a criterion changed mid-build, the contract and its test were updated before merge (no stale spec). | MUST (if triggered) | REQ-API-2, REQ-API-7 |
The merge bar, in one sentence
A change is done when its contract is machine-readable and in sync (REQ-API-2), its behaviour is proven by a contract test at the lowest viable layer (REQ-API-7, QTEST-EARLY), its decision and the why are in an ADR (ENG-PRIN-DOC-STMT), and a named non-author human has signed it off against this list (ENG-PRIN-REVIEW-STMT). Anything less runs, but it isn’t done.
Part of Innovation Day. The five ways: ways-of-working.md. How the gates run: facilitator-guide.md. How it’s scored: scoring-rubric.md.
Downloads for this session
Grab the templates and sample files used here.