Turn what's already been discussed into a spec. Do not interview the user — this skill synthesizes, it doesn't gather. If understanding of the problem is still thin, suggest /grill first and stop.
Process
- Explore the repo to confirm current-state understanding, if not already clear from the conversation.
- Sketch the seams at which the feature will be tested — a seam is the public boundary where behavior gets observed (a function signature, an API response, a rendered view — not an internal call). Prefer existing seams over new ones, and the highest seam available; fewer seams is better, one is ideal. Confirm these with the user before finalizing the spec.
- Write the spec with the sections below and save it per the doc placement protocol.
Spec sections
- Problem Statement — the problem from the user's perspective.
- Solution — the solution from the user's perspective.
- User Stories — a numbered list, each as "As a
<actor>, I want <feature>, so that <benefit>." Cover the feature extensively.
- Implementation Decisions — modules touched, interfaces, architectural and schema decisions, API contracts, specific interactions.
- Testing Decisions — what makes a good test here (external behavior, not implementation detail), which seams from step 2 get covered, and prior art for similar tests in this codebase.
- Out of Scope — what this spec deliberately excludes.
Leave out file paths and code snippets — they go stale fast. Exception: a snippet from a prototype that encodes a decision more precisely than prose (a state machine, reducer, schema, type shape) can be inlined under the relevant decision, trimmed to the decision-rich part and noted as prototype-derived.
Saving the spec
Check .claude/engineering.local.md for a specs: key in its frontmatter — a path, or none to skip saving. If the file doesn't exist, ask once where (or whether) to save this spec, accept "don't save" as an answer, and mention /setup-engineering for making the choice permanent. Never write specs into CLAUDE.md or AGENTS.md.
1---2name: write-spec3description: Synthesizes the current conversation and codebase understanding into a spec document, without interviewing. Use when the user asks to "write a spec", "turn this into a spec", "specにして", or after an interview reaches shared understanding.4---56Turn what's already been discussed into a spec. Do not interview the user — this skill synthesizes, it doesn't gather. If understanding of the problem is still thin, suggest `/grill` first and stop.78## Process9101. Explore the repo to confirm current-state understanding, if not already clear from the conversation.112. Sketch the seams at which the feature will be tested — a seam is the public boundary where behavior gets observed (a function signature, an API response, a rendered view — not an internal call). Prefer existing seams over new ones, and the highest seam available; fewer seams is better, one is ideal. Confirm these with the user before finalizing the spec.123. Write the spec with the sections below and save it per the doc placement protocol.1314## Spec sections1516- **Problem Statement** — the problem from the user's perspective.17- **Solution** — the solution from the user's perspective.18- **User Stories** — a numbered list, each as "As a `<actor>`, I want `<feature>`, so that `<benefit>`." Cover the feature extensively.19- **Implementation Decisions** — modules touched, interfaces, architectural and schema decisions, API contracts, specific interactions.20- **Testing Decisions** — what makes a good test here (external behavior, not implementation detail), which seams from step 2 get covered, and prior art for similar tests in this codebase.21- **Out of Scope** — what this spec deliberately excludes.2223Leave out file paths and code snippets — they go stale fast. Exception: a snippet from a prototype that encodes a decision more precisely than prose (a state machine, reducer, schema, type shape) can be inlined under the relevant decision, trimmed to the decision-rich part and noted as prototype-derived.2425## Saving the spec2627Check `.claude/engineering.local.md` for a `specs:` key in its frontmatter — a path, or `none` to skip saving. If the file doesn't exist, ask once where (or whether) to save this spec, accept "don't save" as an answer, and mention `/setup-engineering` for making the choice permanent. Never write specs into CLAUDE.md or AGENTS.md.
thinceller