to-spec

How it is organised

What’s inside

The skill’s top-level sections, in order. The bar is each section’s share of the 1,295 words, so you can see where the weight sits before reading.

1. 1Principles134 words
2. 2Process197 words
3. 3Saving and publishing147 words
4. 4Template444 words
5. 5Example202 words
6. 6Common mistakes115 words

The skill itself

Read it before you install it

---
name: to-spec
description: Turn what has already been discussed into a written spec or product requirements document (PRD) that a person or an agent can build from: problem, solution, user stories, implementation and testing decisions, out of scope, open questions. Synthesises the conversation and the codebase instead of starting a new interview. Use when the user says "write this up as a spec", "turn this into a PRD", "write the product requirements", "document what we agreed", "to-spec" or "make a spec the agent can build from" once a plan is settled. Saves a Markdown file; publishes to an issue tracker only when asked. Not for exploring an idea that is still open (grill it first), not for splitting a spec into tasks, and not for a one-line ticket.
license: MIT
---

# To spec

A spec is the written record of what is going to be built and why, for a reader who was not in the conversation. This skill writes it from what is already known. It is synthesis, not discovery.

## Principles

1. **Write down what was decided; mark what was not.** Do not invent a requirement, a number, a deadline or a decision. Anything unknown goes under open questions.
2. **Do not start a second interview.** If a gap would change the spec materially, ask about that gap only, briefly. If it can be stated honestly as an open question, state it and carry on. If the idea itself is still unsettled, say so and suggest grilling the plan first.
3. **One spec per effort.** Before writing, look for an existing spec or issue for the same outcome. If one exists, update it instead of creating a second.
4. **Specs are for a reader with no context.** Use the project's own vocabulary and respect its recorded decisions. Do not explain things only the author knows.

## Process

1. **Gather.** Collect the decisions made in the conversation. Read enough of the repository to use its real names: its glossary or decision records if it has them, how its tests are run, and any existing specs or issues on this subject. Explore only what the spec needs.
2. **Choose the test seams.** A seam is a public interface where behaviour can be observed without reaching inside. Decide where the feature will be tested, preferring in order:
   1. an existing end-to-end or behavioural contract,
   2. an existing public boundary or integration test,
   3. a focused unit test of a public interface,
   4. a new lower-level harness, only when none of the above can prove the requirement.

   Use the highest seam that works. Fewer seams across the codebase is better. Show the user the chosen seams and check they match their expectations before you write.
3. **Draft** using the template below.
4. **Check the draft.** Every requirement can be tested. Every actor and every material failure or edge case has a story. Each factual claim traces to the conversation or to something you read. No padding. Terms are used consistently.
5. **Save or publish** (next section), then report.

## Saving and publishing

- **Default: a Markdown file.** Put it in the project's existing specs or plans folder if it has one. Otherwise use `specs/<short-name>.md` at the repository root, and tell the user the path. Export to another format only if asked.
- **Publishing to an issue tracker happens only when the user asks.** Then: take the tracker and repository from the project's own configuration or Git remote, search for an existing issue on the same outcome, and show the final draft before creating anything. Wait for a clear yes. Create exactly one issue, read it back to check the title and every section arrived, and report the link.
- **Do not add readiness or triage labels, create child tickets, branches or pull requests, or mark anything "ready for an agent"** unless the user asked for that.
- Report: the path or link, the open questions, and anything you assumed.

## Template

Omit a section only if it genuinely has nothing in it. Do not fill sections with generic text.

**Problem statement.** The problem from the user's point of view: who has it, what it costs them today.

**Solution.** The solution from the user's point of view, in a few sentences.

**User stories.** A numbered list, each in the form "As a (actor), I want (capability), so that (benefit)", with an id such as US-1 so other documents can refer to it. Cover every actor and every material failure or edge state. Length follows the feature; ten sharp stories beat forty padded ones.

**Acceptance criteria.** Observable and checkable: what appears, what is saved, what response comes back. One check per line. Include at least one failure path where the feature has one (empty input, no permission, missing item, duplicate request). Use a number where a number is needed, and only a number the user gave or you measured. "Fast" and "intuitive" cannot be checked.

**Implementation decisions.** The decisions already made: modules to build or change, their interfaces, schema changes, API contracts, architectural choices, and constraints. Separate a constraint (something external forces it) from a choice (something could be swapped without breaking a promise to the user). Record decisions, not a task breakdown. Do not include file paths, line numbers or code, because they go stale quickly. One exception: a snippet from a prototype that pins a decision down better than prose can (a state machine, a schema, a type shape). Keep only the decision-bearing part and say it came from a prototype.

**Testing decisions.** What a good test looks like here (it checks external behaviour, not implementation details), the seams chosen, which modules are tested, and comparable tests already in the codebase to copy from. Note gaps you could not cover.

**Out of scope.** What this work will deliberately not do. Naming the tempting extras prevents them creeping in.

**Open questions and assumptions.** For each: what is unknown, who can settle it, what you assumed meanwhile, and what it would cost to reverse if the assumption is wrong. Anything that blocks a requirement should say which one.

**For a stakeholder audience** (a PRD for product or business readers), add only what the conversation actually supports: personas, success measures with a stated way to measure them, dependencies, risks and a rough timeline. Do not invent metrics or dates to complete the set. Do not impose a technology choice the user did not make; record the project's real stack or the user's decision.

Priorities are the user's call. If they have given some, record them. Do not invent a priority split or a quota for the top tier.

## Example

A conversation settled on letting accountants export an invoice list as a spreadsheet. The spec would open:

```
# Invoice list export

## Problem statement
Accountants who reconcile invoices copy rows from the invoice list into a
spreadsheet by hand. It is slow and they transpose figures.

## User stories
US-1. As an accountant, I want to export the filtered invoice list as CSV,
so that I can reconcile it without retyping.
US-2. As an accountant, I want the export to match what I filtered, so that
I do not reconcile invoices I excluded.
US-3. As a user without export permission, I want to be told I cannot export,
so that I do not think the button is broken.

## Acceptance criteria
- Choosing Export downloads a CSV with one row per invoice in the current filter.
- Totals in the file equal the totals shown on screen.
- A user without permission gets a refusal and no file is created.
- With zero matching invoices the file has a header row only.

## Open questions
- Maximum rows per export is not decided. Assumed: no limit for now. If
  wrong, add a limit and a message (small change, one story).
```

## Common mistakes

| Mistake | Fix |
|---|---|
| Asking a fresh round of questions | Synthesise, list gaps as open questions |
| Filling in numbers, dates or metrics | Only what the user gave or you measured |
| A huge story list that repeats itself | One story per actor and material case |
| Paths and code in the spec | Name modules and interfaces; keep paths out |
| Publishing straight to the tracker | Save a file; publish only when asked |
| Creating a second spec for the same effort | Find and update the existing one |
| Vague criteria ("works well") | Observable, one check per line |

The second audit

What we found in the sources

This family holds two kinds of skill that end in the same kind of document: a spec written from a conversation that has already settled the plan (mattpocock/skills and its variants), and PRD generators that interview the user from a rough idea (three independent sources). The rewrite keeps the synthesis approach of the first kind, with its test-seam step and template, and takes from the others the habits that make a requirements document usable: observable acceptance criteria, an explicit out-of-scope list, open questions with a default and a cost to reverse, and the rule not to invent numbers, metrics or technology choices. It saves a Markdown file by default and publishes to a tracker only when asked. Every source below was read at the commit the auditor recorded. Nothing was taken from a source without a permissive license.

What each source contributed

• mattpocock/skills ↗ · Primary basis · MIT

  Synthesising the conversation and codebase into a spec without a new interview, using the project's vocabulary and respecting its decision records, choosing the test seams (existing before new, highest practical, as few as possible) and checking them with the user, and the template sections: problem statement, solution, user stories, implementation decisions without file paths or code, testing decisions, out of scope, further notes. Also the exception for a prototype snippet that pins a decision down better than prose.

• rengwu/wayfinder-maps ↗ · Added ideas · MIT

  Defining a seam as a public interface where behaviour can be observed without reaching inside, proceeding silently when no glossary or decision records exist, reusing the existing folder for an effort that already has one, and telling the user the path.

• panda850819/pandastack ↗ · Added ideas · MIT

  The ordered preference for test seams (existing end-to-end or behavioural contract, existing public boundary, focused unit, new harness only when needed), requiring every factual claim to trace to the conversation or inspected repository with unresolved facts listed separately, searching for an existing spec before creating one, showing the full draft and asking once before publishing, creating exactly one issue and reading it back to verify, and creating no child tickets.

• mascah/skills ↗ · Added ideas · MIT

  Asking only about a consequential gap that cannot be stated honestly as an open question, exposing unresolved meaning instead of inventing it, updating the existing canonical spec when scope changes, and the rule that saving a spec does not publish it, create tickets or apply readiness labels.

• GangJaeYu/harness_loop_full_korean ↗ · Added ideas · MIT

  Observable acceptance criteria with at least one failure path and numbers where numbers are needed, one check per line, the test for separating a constraint from a technology choice (would swapping it still keep the promise to the user), and open questions that each carry a default and the cost of reversing it. This source is in Korean; I read its opening, steps 1 to 4 and the headings, and did not read steps 5 to 8 in full.

• jamesrochabrun/skills ↗ · Added ideas · MIT

  An explicit out-of-scope section to prevent scope creep, avoiding vague words, and the optional stakeholder-facing sections (personas, success measures, dependencies, risks, timeline) for a PRD aimed at product readers.

• ognjengt/founder-skills ↗ · Added ideas · MIT

  Asking only for what the input does not already answer, requiring testable acceptance criteria for every feature, preferring specific numbers to vague terms, and recording assumptions in the document.

What changed

• The description now lists the phrases a person would type ("write this up as a spec", "turn this into a PRD", "document what we agreed") and a not-for clause. The mattpocock/skills description says what the skill does but has no trigger phrases, and is set not to trigger on its own.
• The two kinds of source disagree on whether to interview. The rewrite synthesises first, asks only about a gap that would change the spec materially, otherwise lists it as an open question, and suggests grilling the plan if the idea is still open. This is a judgement, not a tested choice.
• Default output is a Markdown file in the project's specs or plans folder, or specs/<name>.md. The primary source publishes straight to an issue tracker and applies a readiness label; the rewrite publishes only when the user asks, after showing the draft and getting a clear yes.
• Removed the dependency on a setup command and a label vocabulary, plugin and tracker configuration, and a question tool, so the skill reads the same in any host.
• Replaced the instruction to write a long, extensive list of user stories with coverage by actor and material case, since a mandated length encourages padding.
• Replaced the <spec-template> and <user-story-example> pseudo-tags with plain headings and a worked example.
• Added open questions with an assumed default and the cost of reversing it, and the constraint-versus-choice distinction for technology decisions.

Problems found in the sources

• !mattpocock/skills: Depends on a setup command and a triage-label vocabulary being supplied, and publishes to the tracker by default with a readiness label, without asking the user to confirm publishing. It tells the agent to write a long, extremely extensive list of user stories, which invites padding, and says the ideal number of test seams is one with no basis given. It wraps its template in pseudo-tags that not every host renders. It sets disable-model-invocation.
• !rengwu/wayfinder-maps: A variant of the primary source (about 87 percent similar by text) that saves to a committed .plan/<slug>/spec.md instead of publishing, so it avoids the tracker dependency. It keeps the instruction for a long story list and the pseudo-tags.
• !panda850819/pandastack: Needs a setup-verbs skill, a tracker setting in AGENTS.md or CLAUDE.md, and an authenticated gh. It adds good controls (search for an existing spec, one confirmation, read-back), but several of them are tied to that setup.
• !mascah/skills: The skill's contract lives in references/discipline.md and references/specification.md, which are not in the downloaded file, so the file alone does not say what a spec contains.
• !GangJaeYu/harness_loop_full_korean: Korean, about 39 KB (about 19,000 characters), written as one layer of a multi-document pipeline and refers to other skills, an idea document and a state file that a lone copy does not have. It says that more than half the requirements being P0 signals too wide a scope, a rule that conflicts with the 30 to 40 percent rule in ognjengt/founder-skills and has no basis stated.
• !jamesrochabrun/skills: About 15 KB. Refers to scripts/validate_prd.sh, scripts/generate_prd.sh and three reference files that are not in the downloaded file. The same advice (be specific and measurable, scope tightly, keep it updated) appears in several sections, and much of the text is generic product-management guidance.
• !ognjengt/founder-skills: Requires reading ./references/prd_template.md, which is not in the file, and a question tool, and runs npx md-to-pdf to produce a PDF, which fetches and runs an npm package. Its defaults pick a technology stack and hosting, its priority split (about 35, 40 and 25 percent) and the 30 to 40 percent P0 rule have no basis, and its sample PRD includes an unsupported figure of 5+ hours per week lost per engineer.

What was dropped

• The PDF conversion step that runs an npm package and writes a prd_outputs folder (ognjengt/founder-skills). Export is only on request.
• Default technology and hosting choices and the mandatory "Implementation Notes for AI" section (ognjengt/founder-skills); the rewrite records the project's real stack or the user's decision.
• Fixed priority splits: 30 to 40 percent P0 (ognjengt/founder-skills), and more than half P0 as a warning sign (GangJaeYu/harness_loop_full_korean). The two differ and neither gives a basis, so priorities stay the user's call.
• Validation and generation scripts and reference templates (jamesrochabrun/skills, ognjengt/founder-skills) that are not in the downloaded files.
• Metrics frameworks, product-manager tips, scenario boilerplate and the repeated best-practice summaries of jamesrochabrun/skills.
• The layered pipeline machinery of GangJaeYu/harness_loop_full_korean: the idea and technical-requirements documents, the state file, traceability tables, the open-question resolution session and the partial-update modes.
• Tracker bindings, a configuration section naming the tracker, and the ownership sentence about not keeping a repository copy (panda850819/pandastack); these are one project's conventions.
• The triage label that marks a spec ready for an agent (mattpocock/skills).

Same text, wherever you work

Use it where you work

git clone https://github.com/nikbearbrown/skills
cp -R skills/skills/to-spec ~/.claude/skills/

Pairs with