Save as .claude/skills/write-a-spec/SKILL.md in a repository, or under ~/.claude/skills/write-a-spec/SKILL.md to have it everywhere. The copy button takes the whole file, frontmatter included.

---
name: write-a-spec
description: Turn a vague request into a specification someone can build from, with the unknowns named rather than guessed. Use when asked to write a spec, scope a feature, plan an implementation, or turn an idea or ticket into something actionable.
---

# Write a spec

The job of a spec is to make disagreement visible before anyone writes code.
A spec that reads smoothly because it quietly invented the answers has failed,
even though it looks finished.

## Separate what you were told from what you assumed

This is the discipline the whole skill rests on. Keep three lists as you work:

- **Given.** Stated by the requester.
- **Assumed.** You filled it in. Every assumption gets written down and
  surfaced, never buried in a sentence.
- **Unknown.** Nobody knows yet, and it blocks or changes the design.

Most bad specs are bad because the second list was silently merged into the
first.

## Structure

### Problem
Who has it, what they do today, and what it costs them. If you cannot name the
person and the current workaround, the problem is not understood yet.

### Outcome
What is true when this is done, in terms someone outside the team could check.
Not "improve onboarding" but "a new user reaches their first saved item without
contacting support".

### Scope
What is included. Then, separately and explicitly, what is not. The second list
prevents more argument than the first.

### Behaviour
The cases, including the ones nobody mentions:

- The normal path.
- Empty: no data, first run, nothing configured.
- Limits: the largest input, the slowest connection, many at once.
- Failure: the dependency is down, the input is invalid, the user leaves
  halfway.
- Permissions: who may do this, who may see the result.
- Existing data: what happens to records created before this change.

### Constraints
Deadlines, systems that cannot change, compliance, budget, team capacity.

### Open questions
The unknown list, each with who can answer it and whether it blocks a start.

## Rules

- **Describe behaviour, not implementation**, unless the implementation is the
  constraint. Say what must be true, and leave the how to the person building
  it, who knows the code better than you do.
- **No invented requirements.** If nobody said it must be real time, it does
  not say real time.
- **Make every statement checkable.** Replace *fast*, *intuitive* and *robust*
  with something measurable, or mark them as open questions.
- **Size the unknowns.** A spec with three blocking unknowns is not ready, and
  saying so is more useful than a complete looking document.
- **Cut what you cannot justify.** If you cannot say who asked for a
  requirement, it is scope creep.

## When the request is too vague to spec

Do not fill the gap with plausible detail. Return the three or four questions
that would unblock it, each with why it matters and what you would assume if
no answer comes. That is a more useful deliverable than a confident document
built on guesses.

## Report back

1. The spec.
2. The assumptions, as a visible list.
3. The open questions, with owners and whether each blocks a start.
4. Anything in the original request you deliberately left out, and why.