owainlewis/blueprint/spec

Spec

Write one implementation-ready specification for one coherent change. The spec is the ticket: its source may be docs/<feature-slug>/spec.md, a GitHub issue, or another user-supplied document. Update the supplied source; do not create a duplicate ticket or document. Without a supplied source, use the Markdown path above. Publish to a tracker only when asked.

Process

1. Read the request, repository instructions, requirements, architecture, and relevant implementation. Reuse settled decisions and verify claims about current behavior.
2. Define the outcome and scope. Ask about unresolved choices that could change behavior, data, interfaces, security, compatibility, operations, cost, or proof. Leave reversible local mechanics to implementation.
3. Write the spec using the shape below. Explain the change from current behavior; link shared requirements and architecture instead of restating them.
4. Check that a fresh agent could implement it without inventing a consequential decision. Trace success, denial, invalid input, and partial failure where relevant.
5. Stop with the spec ready for review. Do not plan tasks or implement it.

Spec shape

Outcome and scope

State the problem, affected user or caller, desired result, constraints, and non-goals.

Required behavior

Describe inputs, actions, observable results, permissions, business rules, and failure recovery. Reference applicable REQ-n IDs. Settle feature-specific product details here.

Technical design

Explain changed responsibilities, interfaces, data, and execution order. Use concrete types, payloads, state tables, or diagrams when they remove ambiguity.

Cover schema changes, indexes, migrations, transaction boundaries, concurrency, retries, cancellation, security, compatibility, observability, rollout, and rollback only where they affect the change. State important choices, their reasons, and their costs.

Name any required change to system architecture. Do not silently override an accepted rule. Record the proposed architecture change for review before delivery.

Acceptance and proof

Pair each observable condition and affected architectural rule with a check.

Preserve existing AC-n, REQ-n, and INV-n references. Never reuse or renumber IDs. Do not invent executable commands for code that does not exist; define the scenario and expected result instead.

Open decisions

State missing answers, recommended defaults when justified, and whether they block delivery. Write None when settled. Do not hide unknowns behind placeholders.

Lifecycle

State the decision status and delivery status separately. After delivery, retain the spec as a record of the feature decisions and acceptance checks. Link delivered PRs and proof without claiming unrun checks passed. Record consequential changes made during delivery; do not erase the reasoning. Keep current product and system rules in requirements and architecture.

Boundaries

One spec may lead to several tasks and pull requests. Use /plan when splitting helps delivery. Small, decided fixes can use their task description and checks without a formal spec. Do not require root documents for a local change that does not need them.

Return

Report the source, main decision and tradeoff, and any blocking question.