spec-writing-best-practices

name	spec-writing-best-practices
description	Write a requirements spec that is testable, scoped, and implementation-aware without turning into architecture. Use this when acting as the spec writer for a task.
owner	spec
trigger	null
version	1

Spec Writing Best Practices

Use this before finalizing a spec deliverable.

Goal

Produce a spec that gives the architect and planner enough clarity to proceed without guessing, while avoiding premature implementation detail.

Checklist

1. Scope the task cleanly. State what is in scope and what is out of scope. Do not leave adjacent work ambiguous.
2. Make acceptance criteria testable. Prefer concrete outcomes, observable behavior, and clear failure conditions. Avoid vague words like "supports" or "handles well" without defining what success means.
3. Separate requirements from implementation. Describe what the system must do. Only mention implementation constraints when they are already required by the existing codebase or the task itself.
4. Capture data and contract expectations. In ## Data Design and ## API Contracts, specify the shapes other agents will depend on. If something is unknown, say so explicitly instead of implying certainty.
5. Include edge cases that can change architecture or testing. Empty input, retries, partial failure, invalid state, missing data, auth failure, concurrency, migration, and backward-compatibility risks are the usual misses.
6. Include non-functional requirements only when they matter. Performance, security, compatibility, observability, and rollout constraints should be concrete and relevant, not boilerplate.

Guardrails

• Do not invent new architecture layers, file boundaries, or agent ownership here. That is for architecture and planning.
• Do not duplicate the same requirement in multiple sections with slightly different wording.
• If the codebase already constrains a decision, read it first and align the spec with reality.
• If the task depends on a third-party API or framework behavior, activate external-api-knowledge before locking the contract language.

Deliverable Standard

Before submitting, ask:

• Could a reviewer derive a meaningful test plan from ## Acceptance Criteria alone?
• Could an architect identify required contracts and data shapes without reinterpreting the task?
• Would two different implementation agents read this spec and reach roughly the same understanding?

If not, tighten the spec before calling submit_deliverable.