/spec-first-delivery

name: spec-first-delivery
description: Force plan, HLD, ADRs, and constraints to exist BEFORE any code is generated. Trigger when starting a new feature, epic, or significant change.

Spec-First Delivery

> **Review the spec harder than the code. The cheapest place to be wrong is the spec.**

The harness runs in this order: spec → plan → tasks → code. Skipping the spec is not faster — it is a deferred rewrite.

When to use

• Any new feature or epic with more than ~1 day of effort
• Infrastructure or architectural changes
• Anything involving a new external dependency, data boundary, or API contract
• Any time an agent offers to "just start coding"

Procedure

1. **Establish the vision artifact** — confirm the project's vision document exists and is current (e.g. `docs/VISION.md` or equivalent per project structure). If not, create or update it before proceeding. 2. **Write the feature spec** — document: what, why, who (user/actor), constraints, acceptance criteria, and out-of-scope. Reject vague specs ("improve performance") in favour of measurable ones ("p99 latency < 200 ms under 1k rps"). 3. **Author or reference the HLD** — a high-level design covering: components affected, data flows, integration points, and failure modes. Diagrams preferred (C4 or sequence). 4. **Create or update ADRs** — one ADR per significant technical decision. Format: Context → Decision → Consequences (trade-offs). Number sequentially (`ADR-NNN`). 5. **Document constraints up front** — security requirements, data residency, budget ceiling, compliance scope, team skill set. Constraints missed here surface as blockers late. 6. **Plan applicable service transition** — identify receiving owner, support, monitoring, runbooks, recovery, knowledge transfer and user acceptance. Schedule their dependencies before the releases they enable; document proportionate non-applicability. 7. **Validate spec completeness** — the spec is done when: acceptance criteria are testable, the failure mode is named, rollback is considered, and cost impact is estimated. 8. **Only then**: generate the implementation plan and tasks. Hand the spec (not a prompt) to the agent.

Use [adoption and evidence guidance](../../docs/HARNESS-ADOPTION.md) when requirements come from conversations or when operational ownership is unclear. A discussion remains a proposal until its accountable owner accepts it within scope.

Outputs

• `requirements/FEATURE_SPEC.md` (or equivalent per project structure)
• `architecture/decisions/ADR-NNN-<short-title>.md` (one per decision)
• `architecture/HLD-<feature>.md` (if not already covered)
• Updated project roadmap (e.g. `docs/ROADMAP.md` or equivalent per project structure) with new tasks or milestones
• Optional `parking-lot.md` beside the spec: questions and ideas raised but not resolved,

each with an owner and the trigger that brings it back. It is a holding list, not a backlog or a delivery record; promote an item by filing an issue, then remove it.

Guardrails

• **No code without a spec.** If an agent begins generating code before a spec exists, stop it and invoke this skill.
• **Loose spec = confident but wrong output.** A vague spec produces plausible-looking, wrong code. Tighten the spec first.
• **Spec is not a prompt.** The spec is a structured document with testable criteria; a prompt is a hint. Do not substitute one for the other.
• **Context efficiency**: Evaluate whether full spec documents are needed, or whether ADRs + plan mode provide sufficient context. Overhead should be proportional to risk.

Anti-rationalization table

| Excuse the agent makes | Counter | |---|---| | "I have enough context to start coding" | No spec = no acceptance criteria = no way to know if the output is correct. Write the spec. | | "The spec will slow us down" | A missing spec causes rewrites. Rewrites cost more than specs. | | "The requirements are obvious" | Obvious requirements are the ones most often wrong. Write them down and verify. | | "We can spec it after the prototype" | Prototypes become production. Spec it now. |