to-spec turns the conversation you've already had into a Spec, and publishes it to the Issue tracker. It doesn't interview you. It only writes up what you've already decided, plus what it learns by reading the code.
When to use it
Use it right after grilling, when every question is settled and the build will take more than one session. It's the step between the interview and the Tickets: grill, then to-spec, then to-tickets.
Run it in the same session as the grilling. The Spec should build on the same thinking, so don't clear or compact the context window until the Tickets are written.
It's the step between the interview and the Tickets
When not to use it
The idea is still fuzzy. to-spec won't ask you anything, so open questions would just be guessed. Get interviewed with grill-with-docs first.
The work fits in one session. Skip the Spec and build it right there with implement.
You already have a Spec and want it split into slices. That's to-tickets.
What it needs to start
A conversation that holds the decisions: usually a grilling session.
The Issue tracker and its labels, set up by setup-matt-pocock-skills. If they're missing, it tells you to run that first.
A few minutes of your time to agree the seams. A seam is a public boundary where tests watch the feature's behaviour from outside. to-spec proposes the highest seams it can, ideally just one, and checks them with you before writing.
What it creates
One Spec, as an Issue on the Issue tracker, labelled ready-for-agent so it needs no further triage. It follows a fixed template:
Problem Statement and Solution, from your point of view;
a long, numbered list of User Stories ("As a ..., I want ..., so that ...");
Implementation Decisions, Testing Decisions, Out of Scope and Further Notes.
It leaves out file paths and code snippets, because they go stale fast. The one exception is a short snippet from a prototype that pins down a decision better than words can. It creates no branches, code or Tickets.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt's page for the Skill (updated 2026-08-24) gives the reason in one line: "The spec exists because context windows end." While you were being grilled, you settled the shape of the solution, argued through choices and refused things. "All of that is in one conversation that you are about to clear. The spec keeps it."
His AI Coding Dictionary says the same from the other side: "The spec exists because sessions are disposable and big work isn't." A fresh session reads the Spec and knows where the work stands, without the old session's noise.
The Skill used to be called /to-prd. Matt renamed it in his v1.1 release (2026-07-08), because the document had outgrown a product document: "A PRD describes things about the actual product itself, whereas we were allowing non-product stuff to leak in."
Matt's development workflow from v1.1 (2026-07-08): grill-with-docs, to-spec, to-tickets, implement, code-review. From aihero.dev, 30 October 2026.
Citations (65)
From snapshot/skills/to-spec/SKILL.md, line 7: “This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know.”
From snapshot/skills/to-spec/SKILL.md, lines 15–17: “Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible.”
From snapshot/skills/to-spec/SKILL.md, line 19: “Write the spec using the template below, then publish it to the project issue tracker. Apply the ready-for-agent triage label - no need for additional triage.”
A record, not a decision. Matt's test for a bad Spec is blunt: "If the spec states something you never said, that is a defect."
The destination and the journey. Matt splits the work into two kinds of document. "The spec is the destination and the decisions that fix it." The Tickets "are the steps that get there. If you change direction, delete the unfinished tickets and keep the spec." So the Tickets are thrown away one by one, and the Spec stays as the one place that holds the reasoning.
The seams travel through the Spec. The seams you agree here are used twice later. tdd "works only at seams you agreed in advance", and code-review checks the diff against the Spec, so a seam nobody agreed to shows up as a review finding. In Matt's words: "Both connections go through this document."
The same idea outside Matt's Skills. Anthropic's Claude Code best practices suggest the same order without a Skill: get interviewed "until you could write the spec, then write it to SPEC.md", then "start a fresh session to build from it". The difference is where the Spec lives: a local file there, an Issue on your Issue tracker here.
A real example
In his workflow video (2026-07-16), Matt uses his AI Hero CLI repo. He asks to "remove most of the internal tooling on this CLI", and gets grilled on it. He says he'd usually just build it in the same session. To show the whole flow, he runs to-spec instead. It takes "all of this 46.1k tokens" of discussion and will "compress it into a document that we can use" later, written to a tracker made of local Markdown files.
The result had "a problem statement, a solution, a bunch of user stories, implementation decisions, testing decisions". He then stays in the same session for to-tickets. He also shows a real Spec from a few days earlier, with "11 sub issues", where "each of these tickets is a single context window session". At the end, code-review "cross-checked every acceptance criteria against the spec".
Where it goes wrong
The label trap. to-spec puts ready-for-agent on the Spec itself. Matt means "no further triage needed", but agents that run on their own can't tell. They "will try to build the whole spec in one run instead of picking up the ticket slices. This is the most-reported problem with the skill." Issue #292 (opened 2026-05-31, still open on 2026-10-30) shows the result: another session "picks up the parent (it still has ready-for-agent), implements everything in one go, and the children become orphans". The current SKILL.md, at the pin commit of 2026-10-29, still applies the label. Matt's advice: "exclude the parent spec explicitly in your AFK agent's prompt, or remove the label after /to-tickets has run." One newer change: v1.3 (released 2026-10-04) moved implement-spec into the Engineering bucket. It does build "the whole spec in one run". But it reads the Spec's Tickets as a task graph and works through them. So the trap is an unattended agent that takes the Spec Issue itself as a single job.
The truncated Spec. "A tracker issue may not return a very large spec in full, and there is no local copy to use instead." That's the practical reason to keep to-tickets in the same session: "Run them in the same window, and /to-tickets never has to fetch the spec again."
The stale Spec. "Nothing keeps it in sync." It goes out of date the first time building teaches you something. What should last goes in GLOSSARY.md and ADRs, not in an edited Spec. Matt's two sources disagree here. His AI Coding Dictionary entry (last changed 2026-06-05) says a Spec changes as work goes on and lists the Tickets with their status. His to-spec page was updated later, on 2026-08-24, and says not to edit it. The newer page wins.
The wrong shape of work. For a refactor, the template fits badly: it "relies heavily on user stories, which do not fit architectural work." Lean on the Implementation and Testing Decisions instead.
The duplicate. It "does not search the tracker for overlapping issues before it writes", so search the Issue tracker yourself in a busy area.
Not reading it. Read at least the seams and the Out of Scope list. And "if the spec surprises you, the grilling was too shallow; the spec is not too long."
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), grill the first feature of the yoga-studio site: a member books a place in a class, and a full class says no. In that same session, run /to-spec.
When it shows you the seams, look for as few as possible. For a FastAPI backend, the HTTP API is a natural single seam to expect.
Read the Issue it opens. Check that you remember making every decision in it, and that Out of Scope lists things you really refused.
If a line surprises you, don't edit the Spec: go back and grill that question.
Note the ready-for-agent label on the Spec. Once to-tickets has run, remove it, so no agent takes the Spec Issue as one job.
Going deeper's Check questions are asked in Next up.
Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
From snapshot/skills/tdd/SKILL.md, line 20: “A seam is the public boundary you test at: the interface where you observe behavior without reaching inside.”
From snapshot/web/aihero.dev/skills-to-spec.md, line 51: “the shape of the solution, the choices you argued through, and what you deliberately refused. All of that is in one conversation that you are about to clear. The spec keeps it.”
From snapshot/web/aihero.dev/skills-to-spec.md, line 70: “Its value is that the tickets are disposable and the spec is not. Each ticket is sized for one fresh context window and then gets deleted or closed, while the spec stays as the one place that records the reasoning behind them.”
From snapshot/web/aihero.dev/skills-to-spec.md, line 67: “agents that poll for ready-for-agent cannot see that difference. They will try to build the whole spec in one run instead of picking up the ticket slices. This is the most-reported problem with the skill.”
From snapshot/web/aihero.dev/skills-to-spec.md, line 79: “Nothing keeps it in sync. In practice it is a snapshot of what you knew at that moment, and it goes out of date the first time implementation teaches you something.”
From snapshot/web/aihero.dev/skills-to-spec.md, line 79: “Your GLOSSARY.md and ADRs are the files meant to last. If you learn something during implementation that should last, put it there, not in an edited spec.”
From snapshot/web/aihero.dev/skills-to-spec.md, line 85: “It also does not search the tracker for overlapping issues before it writes, so a spec can duplicate work that someone already filed, and nothing warns you. If the area is busy, search the tracker yourself first.”
From snapshot/skills/to-spec/SKILL.md, lines 15–17: “The fewer seams across the codebase, the better - the ideal number is one. Check with the user that these seams match their expectations.”
