P02 — first principles: outcome and product specification

Run 2026-08-27-sprint-1-fable · lane S1-L1 · observed 2026-08-27 Status: research only. No implementation, no schema committed.

1. The irreducible problem

A ProductSpec exists to answer one question later, under dispute: did we build the right thing?

Every other property people want from a spec — readability, completeness, traceability — is instrumental to that. This makes the defining requirement falsifiability: a spec that cannot be proven wrong cannot settle the question it exists to settle.

Convert what a client said into statements that can each be shown true or false about a delivered system, without naming how the system is built.

The two halves of that sentence pull against each other, and that tension is the whole design problem. Getting statements out of a vague human favours loose natural language. Making statements checkable favours rigid structure. The survey's central finding is that the entire industry has resolved this tension by picking a side.

2. The gap, stated precisely

Across 51 commercial surfaces and 60 OSS projects, elicitation and computed falsifiability are disjoint. The precise statement, after a verification pass corrected an overreach: no commercial surface does both, and the two OSS projects that do (spec-kit, OpenSpec) combine them by convention with no enforcing engine — nothing prevents an agent emitting a spec with zero clarification markers and shallow scenarios. The gap is in enforcement, not in ideas:

Nothing surveyed does both. This is not a market gap in the marketing sense; it is a structural observation with a clear implication: **elicit into a falsifiable structure**, rather than eliciting freely and formalising afterwards. The formalisation pass is where fidelity dies.

3. Objectives

1. Every requirement is individually checkable against a delivered system.
2. Gaps in understanding are structurally visible, countable, and block promotion.
3. The spec remains implementation-independent until composition.
4. What was agreed is retrievable as an object, not reconstructed from email.
5. The client can read and accept it without learning a notation.

4. Constraints

5. Invariants

1. Every requirement carries a provenance pointer to the client utterance or evidence item that produced it.
2. Every requirement has a computed coverage state, starting UNCOVERED.
3. Ambiguity is written into the artifact at the point of ambiguity, carrying candidate answers.
4. No implementation choice appears in the spec.
5. Acceptance is an explicit, blocking, baselined event.
6. Assumptions made where the client was silent are recorded as assumptions, never as requirements.
7. Spec content quoted from client material is data, not instructions to a downstream build agent.

6. The synthesised minimum ProductSpec

Derived backwards from what composition and verification actually need, not forwards from documentation habit:

ProductSpec
├── outcome            one sentence: the measurable business change
├── buyer + terminal owner   who pays, who is accountable for the workflow
├── workflow           steps, actors, handoffs (from ClientContext evidence)
├── requirements[]     EARS-slotted statements:
│     ├── slots: {precondition?, trigger?, system, response+}
│     ├── atom          which of the 12 atoms it instantiates
│     ├── authority     who may approve any side effect
│     ├── provenance    → client utterance / evidence item
│     ├── coverage      UNCOVERED | COVERED (computed, not asserted)
│     └── evidence_grade  client-stated | observed | inferred | assumed
├── entities[]         with the client's own vocabulary preserved
├── failure_states[]   what happens when the date passes, the record is missing
├── non_goals[]        first-class, mandatory
├── assumptions[]      every default chosen where the client was silent
├── success_criteria[] SC-###: measurable AND technology-agnostic
├── acceptance[]       generated Given/When/Then, linked Validated-By to requirements
├── open_markers[]     NEEDS-CLARIFICATION items, each with candidate answers
└── baseline           signed acceptance event + revision

Two computed gates govern promotion: zero open markers and zero UNCOVERED requirements. Both are mechanical, both refusable, neither is a judgement call. A documented waiver path is required so the gate does not block low-stakes work — an ungoverned gate gets bypassed, and a bypassed gate is worse than none.

7. How confidence and assumptions are represented

The survey answers P02's open question with unusual clarity. Three prior-art options, in descending attractiveness:

1. An unfilled mandatory slot (EARS). Self-evident, needs no scale, and doubles as the next interview question. Strongly preferred.
2. An absent provenance pointer (BuildBetter, inverted): this requirement came from us, not from you.
3. A numeric range (parametric estimation): honest, but only meaningful once scope exists.

Nothing in 51 commercial surfaces represented confidence as a percentage on a requirement. That is mild but real evidence that percentages are not useful here — a finding worth more than the absence of a feature usually is, because the surveyed population had every incentive to add one if it sold.

8. When a prototype replaces a question

The segment's implicit consensus, and the clearest answer available to P02's third open question:

Prototype for look-and-feel. Ask for data and behaviour.

A mockup substitutes recognition for articulation, which is exactly right where the client's taste is the requirement and they cannot describe it. It is worthless for "what happens when the reminder date passes" — only an answer will do. The cautionary limit is a builder that produces a beautiful interface in two minutes with no database and no way to save anything: it answers a question nobody asked while leaving the load-bearing ones untouched.

Boundary case held open: workflow shape fits neither cleanly. A prototype can elicit a reaction to a proposed flow, but the reaction may be about the rendering rather than the flow.

9. Assumptions (labelled)

10. Contradictions held open

1. Rigour vs adoption. DOORS Next proves a requirements model can be complete enough to prove verification at a frozen point in time, and spends most of its usability budget doing it. BMAD is estimated at ~2 months to master versus ~a day for Spec Kit. Every mechanism this lane recommends adds authoring cost, and the survey contains no measurement of where clients abandon. Held open.
2. The best clarification loop found is unauditable. ai-prd-generator has confidence-scored rounds gated at 92/95/100% with multi-judge verification — the most mechanically interesting design in the segment — and it is proprietary commercial software, so those claims are marketing behind a licence key. The idea is attractive and the evidence is inadmissible.
3. Two-audience artifacts have a documented decay mode. Gherkin's justification is that non-technical stakeholders can read it; its well-attested real-world failure is that step definitions become a maintenance burden and scenarios end up written by developers for developers, losing exactly the readability that justified the ceremony. Recommending Gherkin as generated output rather than client-authored input mitigates this, but does not disprove it.
4. Structure makes gaps visible and also makes them easy to fake. Nothing prevents a model emitting a spec with zero clarification markers because it guessed confidently. The structure is real; the rigour depends on what fills it. This is the strongest argument for an independent ambiguity detector rather than trusting the authoring model.

11. Design consequences

1. ProductSpec is a typed graph with a document as one rendering, not a document with links added.
2. Requirements are EARS-slotted internally and rendered in the client's own industry vocabulary externally.
3. Acceptance fixtures are generated from the spec at acceptance time, becoming P14's verification input without a second authoring pass.
4. Repeat engagements produce deltas (ADDED/MODIFIED/REMOVED) against the last accepted baseline; settled requirements are never re-elicited.
5. An implementation-independence linter enforces framework invariant 3 mechanically rather than by reviewer vigilance.
6. Mastering is decided once — the spec masters acceptance scenarios, not the repo — rejecting the dual-mastering drift the tooling documents as an unresolved tension.

12. Unresolved questions for later sprints

• What is the true minimum? This lane derived the spec backwards from P12's needs, but P12's contract is itself unsettled in Sprint 1. The minimum cannot be closed until S2-L4 defines what the composer consumes.
• Does EARS survive contact with five real workflows? Designed as the lane's primary falsifier; not run — the five-workflow proving harness is specified, not executed.
• Who owns the waiver path on the promotion gates?
• How is spec expiry set without engagement data to calibrate the window?
• Can generated Gherkin be trusted enough to skip human formulation review at any scope size?