Build a complete implementation-ready specification

Turn scattered decisions into one implementation contract

A stakeholder asks for an “Unfinished” view in an existing task list. By this point, the problem has been clarified, scope has been bounded, Done has been made observable, and the proposed implementation plan has been reviewed before editing. But if those decisions remain scattered across separate artifacts or conversations, the implementer still has to reconstruct the links between them—and may invent a missing decision.

In this lesson you build Implementation-Ready Spec v1: one reviewable specification that brings together the Problem Brief, Scope Box, constraints, acceptance evidence, and an approved plan with explicit assumptions. Every criterion must be traceable from a named need/problem/scope/constraint source through a plan step to evidence; unresolved contradictions and blocking unknowns must be closed before READY; and executable examples, when useful, remain a technique inside the specification rather than the definition of the specification.

This lesson does not decompose the work into tasks or vertical slices. FND-002 takes the complete specification and performs that decomposition; P05 does not absorb that responsibility.

Estimated active time: 55 minutes.

This lesson is for you if: you already have a Problem Brief, Scope Box, Done Matrix, and Plan Review, but they are not yet one traceable artifact that another person can judge independently.

This lesson is not for: replacing a specification with a long prompt, forcing every requirement into Gherkin, starting task decomposition, guessing blocking unknowns, or implementing code.

Hard prerequisite — FND-001-P04: you must be able to review a concrete plan before editing and record a human ACCEPT/MODIFY/REJECT decision with evidence.

Short prerequisite probe

The packet identity for this probe is fixed: spec_version=PREREQ-SPEC-v3 and plan_version=PREREQ-PLAN-v2. Review this bounded packet; do not invent missing implementation facts.

Source packet:

• SCOPE-P04-01: add an All / Unfinished view choice to the existing task list; no new persistence is approved.
• AC-P04-01: in Unfinished, completed tasks are hidden and unfinished tasks remain visible.
• AC-P04-02: returning to All restores the ordinary visible set.
• CONSTRAINT-P04-01: task schema/storage behavior must not change.

Reviewed three-step plan:

1. PRE-PLAN-01 — connect the view selector to the existing list-view state. Primary Trace: SCOPE-P04-01. Decision-driving unknown: U-P04-01 = the selector integration point has not yet been inspected. Required pre-edit verification: V-P04-01 inspect the current view-state owner/integration point.
2. PRE-PLAN-02 — derive Unfinished from existing task status. Primary Trace: AC-P04-01. Verification fact: VF-P04-01 = the current list contract exposes completed/unfinished status semantics. Required verification: V-P04-02 confirm those semantics on a mixed-status sample.
3. PRE-PLAN-03 — verify Unfinished → All return behavior and non-change of storage/schema. Primary Trace: AC-P04-02; secondary constraint check: CONSTRAINT-P04-01. Verification fact: VF-P04-02 = no schema/storage change is authorized. Required verification: V-P04-03 run the return-to-All check and inspect the contract for non-change.

Write three review lines—Trace, decision-driving assumption/unknown or supplied verification fact, and verification—for PRE-PLAN-01..03. Then give one human ACCEPT/MODIFY/REJECT decision and bind the reason explicitly to both reviewed versions.

PASS: no step lacks a valid Trace; U-P04-01 is not converted into fact; verification is clear before edit; and the decision + reason records the same spec_version and plan_version.

If the probe fails, return only to the matching FND-001-P04 skill: repair Trace assignment if a step has no primary source/criterion; repair assumption/unknown + pre-edit verification if an unknown was guessed; or repair the version-bound decision record if the verdict is not tied to both reviewed versions. A complete specification cannot legitimize an unreviewed plan or a hidden assumption.

Choose the amount of support you need

Every route reaches the same artifact and evidence bar. Only the scaffold changes.

Four-concept route probe

Answer these without reading ahead:

1. Implementation-ready specification: why is it not the same as a long prompt or a descriptive document?
2. Traceability: if a test passes but nobody can tell which criterion it covers, what is missing?
3. Ambiguity/contradiction audit: if two parts of the spec define conflicting behavior, may an AI silently choose the “most reasonable” one?
4. Executable example: when is Given/When/Then useful, and why should architectural constraints not be forced into that form?

4/4 → Fast Path; 2–3/4 → repair only the failed concepts; 0–1/4 → foundation route.

• Foundation: follow the task-list filter case with the full reusable blank scaffold.
• Repair: rebuild only the fragile distinction.
• Experienced/Fast Path: go directly to the independent case with less explanation and more contradiction/unknown pressure.

Fast Path does not lower the evidence bar.

Mental model: a specification connects decisions; it is not a text warehouse

Implementation-Ready Spec v1 is the final connection point before decomposition:

Problem → Scope/Constraints → Done criteria → Reviewed Plan → Implementation-Ready Spec → FND-002 decomposition

The four concepts play different roles:

A strong spec does not need to be large. Its value comes from connected decisions, not documentation volume.

The four foundation concepts

1. Implementation-ready specification

An implementation-ready specification is a single package that makes the problem, scope, constraints, acceptance evidence, and plan-approved assumptions clear enough for implementation to begin without inventing decision-driving requirements. “Implementation-ready” does not mean the entire document is machine-executable.

2. Traceability

Traceability is the followable relationship among the problem, boundary, criterion, plan step, and evidence. A criterion with no plan/evidence path is an orphan; so is a plan/evidence item with no source. Traceability is not the same as writing more documentation—a compact ID-based matrix can be stronger than pages of prose.

3. Ambiguity and contradiction audit

Before READY, inspect decision-driving terms, conflicting statements, and blocking unknowns. Proofreading is not enough: two perfectly grammatical sentences can define incompatible behavior. Keep unresolved decision blockers explicitly OPEN_BLOCKING; do not “complete” the spec by guessing.

4. Executable example (optional technique)

For suitable behavioral rules, a Given/When/Then example—or a simpler equivalent—can make context, event, and observable outcome concrete. With tools such as Cucumber, such examples can connect to step definitions and automated tests. The technique is optional: scope boundaries, architectural constraints, and human approval decisions do not need to be forced into scenarios.

Build Implementation-Ready Spec v1

Do not erase the input artifacts and rewrite everything from scratch. Connect them into one traceable contract:

1. Identity and version: the output has an ID/version and records the identities/versions of the Problem Brief, Scope Box, Done Matrix, and Plan Review inputs; the Plan Review record also preserves the reviewed spec_version and plan_version.
2. Problem/outcome: restate the problem and intended outcome without re-solving the design.
3. Scope Box: keep IN, OUT, and constraints distinct.
4. Acceptance Matrix: give observable criteria stable IDs.
5. Reviewed Plan: record the approved plan and the assumptions the human gate has explicitly allowed; hidden assumptions are forbidden.
6. Trace Map: every row starts from a named need/problem/scope/constraint source, reaches a specific criterion, and then maps to a plan step and evidence. No criterion, plan step, or evidence item may be source-less.
7. Readiness Audit: unresolved contradictions and blocking unknowns must both be zero. A non-blocking unknown may remain only with explicit ownership, impact, and follow-up.
8. Optional executable-example decision: for each suitable rule, record USED with an observable example linked to a criterion, or NOT_USED with a bounded rationale.
9. Boundary note: task breakdown, vertical slicing, and delivery sequencing belong to FND-002 and are not authored here.

Reusable blank scaffold

This scaffold contains only current-lesson fields; do not add task breakdown or vertical slicing.

Spec ID: <id>
Spec version: <version>
Input artifact versions:
  Problem Brief: <id/version>
  Scope Box: <id/version>
  Done Matrix: <id/version>
  Plan Review record: <id/version>
Plan Review binding:
  spec_version: <reviewed version>
  plan_version: <reviewed version>
  gate: <ACCEPT|MODIFY|REJECT as supplied by the reviewed record>
Problem / Outcome: <bounded statement>
Scope IN: <items>
Scope OUT: <items>
Constraints: <items>
Acceptance: <AC IDs + observable criteria>
Reviewed Plan: <PLAN IDs + approved assumptions>
Trace Map: <source need/problem/scope/constraint → criterion → plan step → evidence>
Readiness Audit: <unresolved contradictions + blocking unknowns>
Executable-example decision: <USED + criterion-linked example | NOT_USED + bounded rationale>
FND-002 boundary: <task breakdown / vertical slicing / delivery sequencing remain for FND-002>

Minimum trace row:

If AC-01 has no evidence, the spec is not READY. If PLAN-02 or EV-01 cannot be traced back to a named need/problem/scope/constraint source and criterion, remove it or justify it again.

AI may suggest wording, surface possible orphans, flag contradictions, or critique consistency. Scope, unknown closure, acceptance, and the READY decision remain human-owned and evidence-backed.

Worked case: unfinished-task filtering

The shared case contains an existing list with completed and unfinished tasks. The request is to let the user switch between “All” and “Unfinished” without silently adding persistence, a schema change, a redesign, or unrelated cleanup. Assume the preceding Plan Review has already checked the selected path against evidence and approved it; this lesson does not redesign the plan.

Implementation-Ready Spec v1 — core slices

Output identity: spec_id=TASK-FILTER-SPEC; spec_version=v1

Input versions: Problem Brief=TASK-FILTER-PB-v1; Scope Box=TASK-FILTER-SCOPE-v1; Done Matrix=TASK-FILTER-DONE-v1; Plan Review record=TASK-FILTER-PR-v1

Plan Review binding: spec_version=TASK-FILTER-REQ-v1; plan_version=TASK-FILTER-PLAN-v2; gate=ACCEPT

Named source statements:

• NEED-01: a user needs to focus on remaining work without changing underlying task data.
• SCOPE-IN-01: the user can switch between All and Unfinished and can return to All.
• SCOPE-IN-02: in Unfinished, completed tasks are hidden while unfinished tasks remain visible.
• SCOPE-OUT-01: filter persistence, page redesign, and unrelated cleanup are out of scope.
• CONSTRAINT-01: the task schema/storage contract and the meaning of completed/unfinished do not change.

Problem: NEED-01.

Scope IN: SCOPE-IN-01; SCOPE-IN-02.

Scope OUT: SCOPE-OUT-01.

Constraints: CONSTRAINT-01.

Acceptance:

• AC-01: in Unfinished view, completed tasks are not shown and unfinished tasks remain visible.
• AC-02: switching back to All restores the normal visible set.
• AC-03: boundary/failure handling introduces no schema change or new persistence behavior.

Reviewed plan:

• PLAN-01: connect the view selector to the existing list state.
• PLAN-02: derive the unfinished view from existing task status while preserving scope boundaries.
• PLAN-03: verify mixed-status, all-completed, and return-to-All behavior, plus inspect the contract/schema for non-change.

Trace map:

Readiness audit: unresolved contradictions = 0; blocking unknowns = 0. If new evidence later shows the plan does not fit the real data flow, READY must be revoked and Plan Review reopened.

Optional executable example for AC-01

Scenario: Show unfinished tasks only
  Given the task list contains completed and unfinished tasks
  When the user selects Unfinished
  Then only unfinished tasks are shown

Executable-example decision: USED for AC-01, because the filter behavior is observable and the example is linked to that criterion. The scenario clarifies one behavioral rule. Scope exclusions, the schema constraint, and approval history still belong in other parts of the specification.

Four plausible failures

Failure 1: the spec becomes a long prompt

All decisions are prose, but there are no stable IDs, traces, or readiness states. The implementer must reconstruct relationships. Repair: separate Problem/Scope/Acceptance/Plan/Trace/Audit and find orphaned items.

Failure 2: a test passes but its criterion is unknown

EV-07 = PASS is weak evidence if nobody can identify what acceptance condition it proves. Repair: bind evidence to a specific criterion. Evidence without a source and criteria without evidence are both defects.

Failure 3: a contradiction is hidden by fluent wording

One section says filter persistence is out of scope; another says the selection must survive reload. An AI may silently prefer one interpretation. Repair: record the contradiction, identify the authority/evidence needed, and block READY until it is resolved.

Failure 4: every requirement is forced into Gherkin

Behavioral examples can be excellent, but forcing architecture constraints or scope boundaries into scenarios can distort or lose meaning. Repair: use executable examples only for suitable observable behavior and link them to explicit criteria.

Experienced bridge: when the artifacts disagree

Suppose the Scope Box says “filter persistence is out of scope,” while an old plan note says “store the selection in the URL.” Do not settle the conflict by choosing the architecture you prefer. Check the authority and version of each statement. If the note belongs to a stale plan, mark it stale/deprecated. If it is a genuine new requirement, the current spec is not READY and change control is required.

Add three pressures for experienced practice:

• a known dependency whose exact contract is still unclear;
• two evidence items that imply different interpretations;
• a fluent statement with two decision-driving meanings.

The goal is not to declare READY every time. Sometimes the correct result is NOT_READY — blocking contradiction. Manufactured certainty is a defect, not velocity.

Format choices and trade-offs

• Prose-first spec: natural to read, but trace/orphan detection can be weak.
• Matrix-first spec: strong for independent review and traceability, but mechanical without context.
• Issue/template-based spec: convenient for team workflow, but a template must not become decision authority.
• Executable-example-heavy spec: useful for observable behavior, but not a complete specification by itself.

Implementation-Ready Spec v1 is not tied to one tool or file format. The invariants matter: clear problem and boundary, judgeable acceptance, traceable plan/evidence, no blocking audit defects, and human ownership.

Guided and independent practice

Guided case — Order search

Packet:

• NEED-01: a user must find an order by its full order number.
• SCOPE-IN-01: exact order-number search on the orders page.
• SCOPE-OUT-01: fuzzy search, customer-name search, redesign.
• CONSTRAINT-01: the order schema does not change.
• Done: exact match is observable; no-match is explicit; the existing list path has no regression.
• Input versions: Problem Brief=ORDER-PB-v1; Scope Box=ORDER-SCOPE-v1; Done Matrix=ORDER-DONE-v1; Plan Review record=ORDER-PR-v1.
• Plan Review binding: spec_version=ORDER-REQ-v1; plan_version=ORDER-PLAN-v2; gate=ACCEPT.
• Reviewed Plan: PLAN-01 receive the full number; PLAN-02 use the verified lookup capability; PLAN-03 render match/no-match; PLAN-04 run match/no-match/regression verification.
• Evidence packet: EV-01 lookup-capability review=verified; EV-02 exact/no-match acceptance packet=available; EV-03 existing-list regression verification=required.

Build Implementation-Ready Spec v1. Include at least three acceptance IDs and three complete source → criterion → plan → evidence rows, a readiness audit, an explicit FND-002 boundary note, and an Executable-example decision: USED with a criterion-linked example or NOT_USED with a bounded rationale. Do not write task decomposition.

Independent case — Fast Path destination: Avatar refresh

Closed change-request packet:

• NEED-A1: after a successful avatar replacement, the new image is visible on the next profile visit.
• NEED-A2: failure preserves the current image and shows a clear error.
• CONSTRAINT-A1: the upload API contract and storage provider do not change.
• SCOPE-OUT-A1: crop editor, avatar history, and profile redesign are out of scope.
• Input versions: Problem Brief=AVATAR-PB-v1; Scope Box=AVATAR-SCOPE-v1; Done Matrix=AVATAR-DONE-v1; Plan Review record=AVATAR-PR-v1.
• Plan Review binding: spec_version=AVATAR-REQ-v1; plan_version=AVATAR-PLAN-v2; gate=ACCEPT.
• Reviewed Plan: PLAN-A1 consumes the success/failure result from the existing upload contract; PLAN-A2 on success refreshes the known-owner cache path so the next visit reads the new image; PLAN-A3 on failure preserves the current image and exposes a clear error; PLAN-A4 verifies success/failure and API/provider non-change.
• Evidence packet: EV-A1 upload-contract inspection=verified; EV-A2 cache-ownership record=verified; EV-A3 next-visit success verification=required; EV-A4 failure-preservation/error verification=required; EV-A5 API/provider non-change inspection=required.
• Packet audit state: unresolved contradictions=0; blocking unknowns=0 for this bounded scope.

Build an independent Implementation-Ready Spec v1 that:

1. states problem/scope/constraints without copying filter-case wording;
2. gives success and failure separate criteria;
3. traces each criterion from a named source through plan/evidence;
4. claims readiness only from this packet;
5. records an executable-example decision as USED + criterion-linked example or NOT_USED + bounded rationale;
6. explicitly leaves task/vertical-slice decomposition to FND-002.

If a decision needs information outside this packet, do not guess READY; record the defect.

Readiness check: when is the spec actually ready?

Before declaring READY, answer five questions:

1. Can a new reader reconstruct the problem, boundary, Done, and plan gate without hidden context?
2. Does every criterion trace from a named need/problem/scope/constraint source through plan/evidence, with no orphan plan/evidence items?
3. Are unresolved contradictions and blocking unknowns both zero?
4. Is the executable-example decision recorded—USED with a criterion link or NOT_USED with a bounded rationale—and, when USED, are the steps free of hidden implementation detail?
5. Has the spec avoided taking over FND-002, while blocking decisions remain human-owned?

If a critical answer is no, the artifact is not implementation-ready. Machine validation can check structure and consistency; sufficiency and acceptance still require human review.

Assessment and transfer

Assessment covers five layers: bounded concept explanation, application on a fresh artifact, diagnosis of a plausible failure, a human decision on an ambiguous statement, and transfer to a different domain.

For blocking items to pass:

• all four concepts must be visible in the artifact; for the optional executable-example concept, USED or NOT_USED must be recorded with evidence/rationale;
• Implementation-Ready Spec v1 must be judgeable without oral explanation;
• the FND-002 boundary must remain intact;
• the final readiness decision must not be delegated to AI;
• transfer must be more than renaming nouns from the task-list case.

The lesson’s final evidence is the specification itself plus its trace/audit and decision record. This does not prove implementation skill or mastery of the entire canonical FND-001.

References and freshness

Two external references give useful context for the practices used in this lesson:

• ISO/IEC/IEEE 29148:2018 remains the published Edition 2; a later Edition 3 is still under development and has not replaced it.
• Official Cucumber documentation continues to describe Gherkin/executable specifications and Given/When/Then behavior examples. In this lesson, executable examples therefore remain an optional technique, not a required representation for every kind of requirement.

These references support the requirements/specification practices discussed here. They do not replace the concrete Problem, Scope, Done, reviewed Plan, and evidence that your own Implementation-Ready Spec v1 must contain.