Reference · the completeness testReferencia · el test de completitud
When is your spec complete?¿Cuándo está completa tu spec?
Completeness is not length. A spec is complete when a stateless reader can derive the right thing from it alone — when it closes the output space to the correct programs. Every open degree of freedom is a place the AI will guess.
La completitud no es longitud. Una spec está completa cuando un lector sin estado puede derivar lo correcto solo con ella — cuando cierra el espacio de salidas a los programas correctos. Cada grado de libertad abierto es un lugar donde la IA adivina.
Assume nothing — but do not specify the how. A descriptive spec floors the model to the literal minimum; a prescriptive one recovers the full intent. Specify intent and constraint, and let the executor derive the implementation.
Assume nothing — pero no especifiques el cómo. Una spec descriptiva lleva al modelo al mínimo literal; una prescriptiva recupera la intención completa. Especificá intención y restricción, y dejá que el ejecutor derive la implementación.
What a complete spec MUST carryQué DEBE llevar
- Identity + boundary — what the system is, and is not.Identidad + límite — qué es el sistema, y qué no.
- Normative acceptance criteria per feature (RFC 2119 MUST / SHOULD / MAY) — every MUST is a probe.Criterios de aceptación normativos por feature (RFC 2119 MUST / SHOULD / MAY) — cada MUST es un probe.
- Closed decisions with their why (ADR / EDR) — an open decision is a degree of freedom.Decisiones cerradas con su porqué (ADR / EDR) — una decisión abierta es un grado de libertad.
- Contracts — types and tests-as-spec.Contratos — tipos y tests-como-spec.
- Constraints + prohibitions, tied to real incidents.Restricciones + prohibiciones, atadas a incidentes reales.
- Navigation — the sentinel routes to the right slice; and the verifying gates.Navegación — el sentinela rutea a la porción correcta; y los gates que verifican.
What it MUST NOT carryQué NO debe llevar
- The how — the implementation procedure. The executor derives it; specifying it removes the leverage and ages badly.El cómo — el procedimiento de implementación. El ejecutor lo deriva; especificarlo quita el apalancamiento y envejece mal.
- Over-marking — keyword only the load-bearing lines.Sobre-marcado — keyword solo las líneas que cargan peso.
- Restated defaults the activated domain schema already implies. Over-specification is harness excess — match the specificity dial to the stakes.Defaults repetidos que el schema de dominio ya implica. La sobre-especificación es exceso de harness — ajustá el dial de especificidad al riesgo.
The self-testEl self-test
Per requirement: if you handed only this to a stranger with no context, would they build the right thing, or guess? Where they would guess is the missing constraint — add it. Reframe every past defect as the constraint that, had it been present, would have ruled it out.
Por requisito: si le dieras solo esto a un desconocido sin contexto, ¿construiría lo correcto, o adivinaría? Donde adivinaría está la restricción faltante — agregala. Reformulá cada defecto pasado como la restricción que, de haber estado, lo habría descartado.
Template — a complete feature specTemplate — una spec de feature completa
# F-NNN — feature name
Intent: what this must achieve, in domain terms
Scope: in / explicitly out (Bounded)
Acceptance criteria (normative, each a probe):
- MUST observable, checkable behaviour
- SHOULD defeasible; deviation needs a recorded reason
- MAY permitted, ungated
Contracts: types/interfaces (error contract); behaviours pinned by tests
Decisions (ADR/EDR): closed choices + why
Constraints/prohibitions: inviolable rules, forbidden patterns
Verification: which gates check this
Routing: where this lives in the sentinel tree
Keyword only the load-bearing lines. If a stranger could still guess wrong, a constraint is missing.
Keyword solo las líneas que cargan peso. Si un desconocido todavía puede adivinar mal, falta una restricción.