Skip to content

A spec is one internal implementation artifact

Status

Accepted — 2026-08-29. Recorded because the opposite assumption had already produced a duplicated spec in a live project, and because it was re-derived twice inside a single working session before anybody wrote it down.

Context

C010 (VisiTerminal) hands its specs to a developer who runs an external, spec-first workflow. He re-narrates each spec into that tool's own spec.md, so the same feature exists as two specs in two repositories. His copies froze on 2026-07-23; the declared source moved 92 lines on 2026-08-06. Three of the four questions his plan deferred to a stakeholder walkthrough had been answered upstream in the meantime, and neither side could see it.

Two justifications were offered for keeping the split, and both failed on inspection:

  1. "The upstream spec must stay implementation-neutral for customer acceptance." It does not. Customer acceptance happens a stage earlier, on a prototype, at the business level (/vt-d-pd-3-prototype → /vt-d-pd-4-validate). The spec is written after that question is settled. In C010 this was already documented — ADR-002 there excludes the customer-facing documents from the spec corpus by name — and the constraint was nevertheless invented a second time during analysis.
  2. "The upstream spec is not technical enough to plan from." Also not a reason for a second spec: the same corpus already names EDIFACT segments, field identifiers and, once anchored, target module and persistence entity. Where anchoring is missing, the fix is to anchor the spec — not to write a rival.

What the re-narration genuinely produced was engineering decisions — nine of them in the case examined. Those are real and worth keeping. They are also exactly what /vt-d-shape produces into decisions.md, next to the spec rather than in competition with it.

Decision

One spec per feature. It is internal, implementation-anchored, and nobody signs it off.

  • Customer or stakeholder acceptance belongs to the design phase, on a prototype, before spec generation.
  • Engineering decisions belong in decisions.md (/vt-d-shape), plan and breakdown in plan.md / tasks.md (/vt-d-2-plan).
  • Specs may and should name repos, modules, entities, and the places where a choice is configuration rather than code.
  • Internal work needs no external spec-first tooling; the toolkit chain covers the same ground without a second artifact.

Where a copy is unavoidable during a transition, it must record the version it was transcribed from, not merely the path.

Consequences

  • docs/concepts/what-a-spec-is.md carries the reasoning and is linked from the concepts index and from the spec-generation bridge in two-workflows.md.
  • Skills that anchor specs to a customer-review audience should be read again with this in mind.
  • The Knowledge Work workflow is untouched: there the deliverable is the artifact and is very often customer-facing.

References

  • docs/concepts/what-a-spec-is.md
  • docs/concepts/two-workflows.md — the design/development bridge
  • intake/pending/from-projects/2026-08-29-spec-kopien-driften-ohne-dass-es-jemand-merkt.md — the transitional case, where two copies still exist