To spec
Contract
| Field |
Bound contract |
| Trigger |
Settled decisions need synthesis into an implementation spec. |
| Authority |
Reversible local: writes only a named local spec file; rollback is deleting that file. No remote mutation. |
| Side effect |
Writes an agent-ready specification file locally and stops before publishing or distributing it; a human performs any publication. |
| Done |
Problem, solution, stories, decisions, tests, and exclusions are agent-ready in a verified local specification file; publication remains an unexecuted human handoff. |
Inputs
- Conversation context. The current conversation must contain settled decisions: what is being built, why, and how completion will be judged. If the conversation lacks settled decisions, stop and state what is missing.
- Codebase state. Explore the repository to understand the current state. Use the project's domain glossary vocabulary throughout the spec and respect any ADRs in the area being touched.
- Optional: CONTEXT.md or domain docs. If present, read them for vocabulary and constraints. Do not require them.
Refusals
- Will not interview the user or open a new round of questioning: synthesize what has already been decided.
- Will not fabricate decisions or fill gaps with assumptions.
- Will not publish, distribute, or assign labels: publication is a human handoff.
- Will not proceed to spec writing until the user confirms the identified seams.
Procedure
- Explore the repository to understand the current state of the codebase if not already done. Identify the project's domain vocabulary and any ADRs in the relevant area. Done when: the codebase state and domain vocabulary are understood.
- Identify the seams at which the feature will be tested. Prefer existing seams to new ones, and use the highest existing seam possible. If a new seam is needed, propose it at the highest practical point. Fewer seams across the codebase are better; the ideal number is one. Done when: the testing seams are identified.
- Present the identified seams to the user and confirm they match expectations. Do not proceed until the user confirms. Done when: the user confirms the seams.
- Synthesize the spec from the conversation context, codebase understanding, and confirmed seams. Do not interview the user or open a new round of questioning. Capture what has already been decided. Done when: the spec content is synthesized from settled decisions.
- Write the spec to
docs/specs/<feature-slug>-spec.md using the template below. Done when: the spec file is written to disk.
- Verify the written file contains all seven sections populated with substantive content. If any section is empty or stubbed, fill it before declaring done. Done when: all seven sections are substantive.
- Stop. Do not publish, distribute, or assign labels. Report the file path and that publication is a human handoff. Done when: the file path is reported and no publication action is taken.
Spec template
Write the spec using this structure:
# <Feature name> - spec
### Problem statement
The problem from the user's perspective.
### Solution
The solution from the user's perspective.
### User stories
A numbered list of user stories. Each in the format:
1. As an <actor>, I want a <feature>, so that <benefit>
Cover all aspects of the feature exhaustively.
### Implementation decisions
A list of implementation decisions:
- Modules to build or modify
- Interfaces to modify
- Technical clarifications
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions
Do NOT include specific file paths or code snippets unless a prototype produced a snippet that encodes a decision more precisely than prose (state machine, reducer, schema, type shape). Trim to the decision-rich part.
### Testing decisions
- What makes a good test (external behavior only, not implementation details)
- Which modules will be tested
- Prior art for similar tests in the codebase
### Out of scope
What is deliberately excluded from this spec.
### Further notes
Any additional notes about the feature.
Failure and recovery
| Failure class |
Behavior |
| Missing settled decisions |
Stop. Report exactly which decisions are missing. Do not fabricate decisions or fill gaps with assumptions. |
| No seams identifiable |
Propose seams at the highest reasonable points and present them as proposals, not facts. |
| User rejects seams |
Ask what they would prefer and iterate. Do not proceed to spec writing until seams are confirmed. |
| Write failure |
Report the error. No partial artifact is acceptable; delete any incomplete file. |
| Non-convergent synthesis |
Name the contradiction and stop rather than choosing a side silently. |
Output
A local specification file at docs/specs/<feature-slug>-spec.md with all seven sections (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes) populated and agent-ready, publication is a separate human step.
1---2name: to-spec3description: Use when settled conversation decisions need synthesis into an agent-ready implementation spec, stopping before publication. Not for turning plans into tickets: use to-tickets.4---56# To spec78## Contract910| Field | Bound contract |11|---|---|12| Trigger | Settled decisions need synthesis into an implementation spec. |13| Authority | Reversible local: writes only a named local spec file; rollback is deleting that file. No remote mutation. |14| Side effect | Writes an agent-ready specification file locally and stops before publishing or distributing it; a human performs any publication. |15| Done | Problem, solution, stories, decisions, tests, and exclusions are agent-ready in a verified local specification file; publication remains an unexecuted human handoff. |1617## Inputs1819- **Conversation context.** The current conversation must contain settled decisions: what is being built, why, and how completion will be judged. If the conversation lacks settled decisions, stop and state what is missing.20- **Codebase state.** Explore the repository to understand the current state. Use the project's domain glossary vocabulary throughout the spec and respect any ADRs in the area being touched.21- **Optional: CONTEXT.md or domain docs.** If present, read them for vocabulary and constraints. Do not require them.2223## Refusals2425- Will not interview the user or open a new round of questioning: synthesize what has already been decided.26- Will not fabricate decisions or fill gaps with assumptions.27- Will not publish, distribute, or assign labels: publication is a human handoff.28- Will not proceed to spec writing until the user confirms the identified seams.2930## Procedure31321. Explore the repository to understand the current state of the codebase if not already done. Identify the project's domain vocabulary and any ADRs in the relevant area. **Done when:** the codebase state and domain vocabulary are understood.332. Identify the seams at which the feature will be tested. Prefer existing seams to new ones, and use the highest existing seam possible. If a new seam is needed, propose it at the highest practical point. Fewer seams across the codebase are better; the ideal number is one. **Done when:** the testing seams are identified.343. Present the identified seams to the user and confirm they match expectations. Do not proceed until the user confirms. **Done when:** the user confirms the seams.354. Synthesize the spec from the conversation context, codebase understanding, and confirmed seams. Do not interview the user or open a new round of questioning. Capture what has already been decided. **Done when:** the spec content is synthesized from settled decisions.365. Write the spec to `docs/specs/<feature-slug>-spec.md` using the template below. **Done when:** the spec file is written to disk.376. Verify the written file contains all seven sections populated with substantive content. If any section is empty or stubbed, fill it before declaring done. **Done when:** all seven sections are substantive.387. Stop. Do not publish, distribute, or assign labels. Report the file path and that publication is a human handoff. **Done when:** the file path is reported and no publication action is taken.3940### Spec template4142Write the spec using this structure:4344```markdown45# <Feature name> - spec4647### Problem statement4849The problem from the user's perspective.5051### Solution5253The solution from the user's perspective.5455### User stories5657A numbered list of user stories. Each in the format:58591. As an <actor>, I want a <feature>, so that <benefit>6061Cover all aspects of the feature exhaustively.6263### Implementation decisions6465A list of implementation decisions:66- Modules to build or modify67- Interfaces to modify68- Technical clarifications69- Architectural decisions70- Schema changes71- API contracts72- Specific interactions7374Do NOT include specific file paths or code snippets unless a prototype produced a snippet that encodes a decision more precisely than prose (state machine, reducer, schema, type shape). Trim to the decision-rich part.7576### Testing decisions7778- What makes a good test (external behavior only, not implementation details)79- Which modules will be tested80- Prior art for similar tests in the codebase8182### Out of scope8384What is deliberately excluded from this spec.8586### Further notes8788Any additional notes about the feature.89```9091## Failure and recovery9293| Failure class | Behavior |94|---|---|95| Missing settled decisions | Stop. Report exactly which decisions are missing. Do not fabricate decisions or fill gaps with assumptions. |96| No seams identifiable | Propose seams at the highest reasonable points and present them as proposals, not facts. |97| User rejects seams | Ask what they would prefer and iterate. Do not proceed to spec writing until seams are confirmed. |98| Write failure | Report the error. No partial artifact is acceptable; delete any incomplete file. |99| Non-convergent synthesis | Name the contradiction and stop rather than choosing a side silently. |100101## Output102103A local specification file at `docs/specs/<feature-slug>-spec.md` with all seven sections (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes) populated and agent-ready, publication is a separate human step.
OutlineDriven