Spec-driven development for product teams: turn evidence into a testable decision

Spec-driven development for product teams turns evidence into one testable decision, then carries that decision through implementation and learning. A spec sets the intended outcome, boundaries, and owner of unresolved policy while leaving pixel-level and engineering choices visible for the people responsible for them. For a broader engineering definition, see Martin Fowler's overview of spec-driven development tools.

A useful spec makes one product decision inspectable: the outcome being pursued, evidence supporting it, what must remain true, choices that belong to engineering, and what the team will learn after release. It helps humans and coding agents by exposing policy gaps before implementation fills them silently.

Evidence, decision, implementation, learning

Each arrow has an owner and a handoff. Interviews and analytics inform the product decision; that decision establishes the requirements. The spec records the decision in a form engineering can challenge. Implementation produces observable behavior. Learning decides whether the original decision should stand, change, or be retired.

When a handoff disappears, research decks fail to affect scope, detailed tickets lose their rationale, and shipped features have no agreed signal of success.

How a product spec differs from a PRD

A PRD can explain the problem, audience, and desired direction. The product spec used here records the decision that implementation must test: the evidence that changed the decision, the boundaries that must hold, unresolved ownership, and the learning plan. A PRD may feed a spec; it is not enough on its own when a team needs to decide what behavior to build and how it will know whether that decision held up.

A decision packet is a compact version of this practice for a consequential handoff. Repository instruction files then tell coding agents how to work within the repository. Keep the supporting material in an evidence-linked context layer, not in a growing spec appendix.

Worked example: recover a draft after an expired session

The following is an illustrative composite. Imagine a writing product where users sometimes lose work after a session expires. Support reports it, but does not show whether people expect automatic recovery, explicit saving, or a warning before expiry.

Support reports describe a long edit followed by a save attempt after expiry. The evidence supports a narrow problem: work is vulnerable during an expired-session transition. It does not establish a claim about all data loss.

The decision is: “When a save fails because the session expired, preserve the local draft and offer sign-in followed by an explicit restore; do not silently submit it under a new session.” It chooses safety and user agency over a deceptively smooth automation.

The spec defines the state transition, data boundary, failure behavior, and evidence of success.

# Preserve drafts across session expiry Status: confirmed • Owner: product owner • Date: <decision date> Outcome An editor who hits Save after session expiry can sign in and restore the exact unsaved draft before any server write occurs. Evidence Support review: reports involved a long edit plus an expired session. In scope - editor draft state; save error handling; sign-in return path; restore UI Out of scope - cross-device draft sync; background autosave redesign; account recovery Rules - Keep the encrypted local draft for 24 hours or until restored/discarded. - Do not send the draft to the server until the person chooses Restore. - If local storage is unavailable, show the existing save error and explain that recovery is unavailable. Open engineering choice Choose IndexedDB or existing encrypted draft storage; document size and cleanup implications. Acceptance evidence 1. Expire a session with a modified draft, press Save, sign in, and restore the identical text. 2. Choose Discard and confirm no draft is sent. 3. Disable local storage and confirm the fallback message appears. 4. A normal authenticated save remains unchanged. Learning plan Review recovery-started, restore-completed, discard, and storage-unavailable events on a stated date. No target is claimed until a baseline is established.

The engineer may choose the storage mechanism while preserving the user’s choice to restore. The agent can map rules to the client draft store, authentication callback, editor state machine, analytics event definitions, and tests.

The team reads the events with the support queue. If people initiate recovery but abandon it, the sign-in return path may be poor. If storage-unavailable is common, revisit the implementation boundary. The review creates a scheduled product decision.

Bad spec versus usable spec

| Bad | Usable |

| --- | --- |

| “Prevent users from losing drafts.” | “On an expired-session save failure, retain the local draft for 24 hours and require explicit restore after sign-in.” |

| “Use local storage.” | “Keep the draft locally; engineering chooses the existing encrypted store or IndexedDB and records the tradeoff.” |

| “Make it intuitive.” | “A person can restore or discard before any write; both outcomes are visible.” |

| “Track success.” | “Emit named recovery events; owner reviews their relationship to support cases on a stated date.” |

The usable column gives a reviewer a claim that can be wrong.

A reusable spec skeleton

# <decision name> Status: proposed | confirmed | superseded Owner: <decision maker> • Date: <date> • Replaces: <link or none> Outcome <One observable change for a user or operator.> Evidence <The source and the interpretation that affects this decision.> In scope / Out of scope <Bound the work and name tempting adjacent work explicitly.> Rules and constraints - <data, authorization, compatibility, policy, or UX rule> Open engineering choices - <choice plus criterion; do not disguise it as decided> Relevant surfaces <systems, contracts, designs, and migrations; avoid every file> Acceptance evidence 1. <happy-path behavior> 2. <negative or unsafe case> 3. <compatibility/migration case when relevant> Learning plan <events or qualitative signal, baseline, owner, and review date>

Questions a spec should settle

Before implementation, a product owner should be able to answer: “What would make this decision wrong?” In the draft-recovery example, a security review might show that local retention is unacceptable for a particular class of document. That is a decision-changing fact. A front-end engineer might show that sign-in return paths already preserve editor state, reducing the surface area. That is an implementation insight. The spec is doing its job when it distinguishes these two kinds of challenge.

The tech lead should also be able to name the engineering choices. Storage mechanism, cleanup implementation, and test fixture design are technical choices because the spec supplies their constraints. Move an unresolved choice into the spec, attach a criterion, and name its decision owner.

At PR review, use the spec as a checklist. Link each acceptance item to a test, a manual verification step, or a deliberate exception. Note deviations in the decision record so a later incident or learning review can explain the tradeoff.

Failure modes worth designing against

A spec launders weak evidence into certainty

“Customers asked for it” gives a reviewer nothing to inspect. Link the study, support synthesis, or experiment and state the inference. If the evidence is directional, label the decision as a bet.

The spec dictates architecture to sound complete

Product should specify a privacy boundary or a latency requirement rather than prescribe a queue technology without a reason. Put the decision criterion in the spec and let engineering own the mechanism. If architecture is itself the product risk, make it an explicit engineering decision with an owner.

A decision hides in an acceptance criterion

“Should work for all users” can quietly create a rollout, localization, accessibility, and permissions project. Name such scope. If it cannot fit, split it before implementation.

No one returns to learn

Event names without a baseline, owner, and review date create an instrumentation request. A lightweight plan is enough; it must be scheduled.

What specs cannot do

A spec cannot validate an untested market assumption, settle a political dispute about priorities, or make a risky migration reversible. It can make those limits legible early enough to change the plan. For exploratory work, write a hypothesis and a stopping condition instead of pretending you have a decided customer outcome. For urgent incidents, write the smallest decision record after containment, then use it to guide the durable fix.

The danger is treating a template as proof of understanding. A complete-looking skeleton with vague evidence is still vague. The standard remains simple: can a skeptical engineer identify the intended behavior, the boundary, the owner of ambiguity, and the observation that could make the team revisit the decision?

Adopt the habit without a document factory

For an initial trial, require the skeleton only for changes that alter permissions, stored data, a customer workflow, or an irreversible action. Keep each spec to one decision. Pair the product owner and tech lead for a short review before implementation. In PR review, require a brief trace from acceptance evidence to tests or manual checks. After release, the decision owner posts the learning result, even when the answer is “we do not know yet.”

Then inspect friction. If every spec repeats the same compatibility rule, move it to a repository contract. If teams argue over the outcome field, bring that product decision forward.

For the next multi-file customer change, write the outcome, one evidence link, one boundary, one negative acceptance check, and a review date. Bring unresolved decisions to the owner before implementation begins.