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 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

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