Skip to content

What a Spec Is

A spec is an internal implementation artifact. Exactly one exists per feature. It carries the business rules, the evidence behind them, the acceptance criteria, and enough implementation anchoring that a planner does not have to invent it.

It is not a customer-facing document, and it is not the thing anyone signs off.

Why internal — the acceptance already happened

The design phase settles the business question before a spec exists. /vt-d-pd-3-prototype builds something deployable, /vt-d-pd-4-validate puts it in front of real users, and that is where the customer says yes or no. Only then does spec generation run.

The toolkit already names this: /vt-d-specs-from-prd sits under "Spec Generation (bridge between design and development)" in Two Workflows. Everything before the bridge is agreement; everything after it is construction.

A spec written for customer sign-off would therefore be the right document at the wrong time — and it would be shaped by the wrong reader. Writing for a customer pushes implementation detail out; writing for an implementer pulls it in. A spec that tries to do both does neither.

Scope. This describes the spec-driven Unified Product Development path. In the Knowledge Work workflow the deliverable is the artifact — a document, a policy, a report — and it is very often customer-facing. The distinction below applies to specs, not to deliverables.

Therefore: one spec, not two

The tempting failure is a second, "implementation-facing" spec that re-narrates the first. It shows up wherever an external spec-first tool wants its own spec.md at the entry point, and it is always a mistake for internal work.

Not because the second pass is worthless — it usually is not. In the case that produced this document, the re-narration resolved nine genuine engineering decisions, one of them by reading backend tests and finding a documented contract to be aspirational. That work is valuable.

It simply does not need a rival spec to live in. The toolkit already has homes for every part of it:

What Where Produced by
Business rules, evidence, acceptance criteria, implementation anchors spec.md — one /vt-d-specs-from-prd, /vt-d-spec-from-requirements
Engineering decisions — the gray areas resolved before planning decisions.md /vt-d-shape
Approach and breakdown plan.md, tasks.md /vt-d-2-plan
The evidence the spec cites meeting records, change analyses the project

/vt-d-shape is defined as "identifies gray areas in a spec and locks implementation decisions before planning begins". That is exactly the slot a second spec would occupy — and decisions.md sits next to the spec instead of competing with it.

What "implementation-anchored" means

Concretely, and no further:

  • Name the target. Which repo, which module, which entity will hold the data.
  • Say where the decision is configuration rather than code. That single sentence redirects a planner who would otherwise open the wrong file.
  • Keep the words fixed, not the tables. The spec prescribes the vocabulary every other artifact refers to; the schema belongs to the implementation. Renaming a field in the spec is a spec change; renaming a column is not.

Why a second spec goes stale, with numbers

The pattern is not hypothetical. In C010 an external implementer did the honest thing — his generated spec carried a Source of truth: line pointing at ours, a line his template does not even have. It was still worthless within three weeks:
His copy frozen at 2026-07-23
The declared source since three commits, one of them +61 / −31 lines
Consequence his plan deferred four questions to a stakeholder walkthrough; three had been answered upstream weeks earlier

A citation without a version is a citation nobody can check. Two artifacts holding the same truth will diverge, and the only reliable fix is not to create the second one.

Consequences for the toolkit

  • Internal work needs no external spec-first tooling. The chain spec → shape → plan → build → review covers specify, clarify, plan and tasks already, and it does so without a second artifact.
  • Specs may name modules, classes and entities. That is not a leak of implementation detail into a business document — the spec is the implementation document.
  • A spec handed to someone outside the workflow should carry a version, not just a path, if a copy is unavoidable during a transition.