Specifications define what the system must do before implementation details take over. Create one for behavior that changes a public API, crosses module boundaries, introduces a durable data format, or has meaningful operational constraints.
Use a short kebab-case filename such as retry-policy.md. Each specification
should contain:
- Status and owner — Draft, Accepted, Implemented, or Superseded.
- Problem — the user or system need, without prescribing a solution.
- Goals and non-goals — the exact boundary of the work.
- Proposed behavior — public API, inputs, outputs, errors, and examples.
- Invariants and constraints — properties every implementation must keep.
- Acceptance criteria — externally observable pass/fail conditions.
- Open questions — unresolved decisions that block acceptance.
After the specification is accepted, create a linked implementation plan in
../plans/. Keep code snippets small enough to clarify
the contract; production code still belongs under src/.
See example-retry-policy.md for a complete sample.