to-spec - Turn Conversations Directly into Requirements Specifications and Publish Them to an Issue Tracker

Skill Overview

to-spec is a requirements specification generation skill in the superpowers skill set. It does not ask you questions; instead, it directly synthesizes the current conversation and its understanding of the codebase into a structured spec, automatically publishes it to the project issue tracker, and adds the ready-for-agent label.

Use Cases

1. Turning a brainstorming session into a formal document

   You have just discussed how to implement a new feature with AI. The ideas are all in the conversation, but there is no document that others can read and follow. to-spec directly synthesizes the discussion into a spec without requiring you to restate everything from scratch.

2. Synchronizing completed requirements discussions with the team’s issue system

   After generating the spec, it automatically publishes it to the project issue tracker and adds the ready-for-agent label. There is no need to manually copy and paste it into Jira, Linear, or GitHub Issues, or manually apply the label.

3. Fixing the technical approach before modifying code

   to-spec first explores the repository and understands the current codebase, then documents implementation decisions, testing decisions, and out-of-scope items in the spec. It is suitable for locking down an approach before a refactor or a new feature, and for projects that need to follow existing ADRs and domain terminology glossaries.

Core Features

1. No-Interview Synthesis

   This is to-spec’s most distinctive characteristic: it explicitly does not conduct requirements interviews. It only synthesizes “what you have already discussed.” It is suited to situations where the ideas have already taken shape in the conversation and only need to be formalized, eliminating another round of questions and answers.

2. Test Seam Planning and Confirmation

   Before writing the spec, to-spec first outlines the seams at which the feature should be tested: it prioritizes reusing existing seams, prefers the highest-level seam, and aims to minimize the total number of seams across the codebase—the ideal case is a single seam. New seams should be introduced as high as possible, and to-spec first confirms with you that the proposed seams meet expectations before writing the spec.

3. Structured Spec Template + Automatic Publishing

   The spec follows a fixed template and includes: problem statement, solution, an extensive numbered list of user stories, implementation decisions, testing decisions, out-of-scope notes, and additional notes. The implementation decisions intentionally omit specific file paths and code snippets to prevent the document from becoming outdated quickly. The only exception is when a prototype encodes a decision more precisely than prose—such as a state machine, reducer, schema, or type shape—in which case it is trimmed, embedded inline, and identified as coming from the prototype. Once complete, the spec is published to the issue tracker and directly labeled ready-for-agent, requiring no additional triage.

Frequently Asked Questions

What is to-spec? How is it different from brainstorming?

Brainstorming is the exploration phase—it helps you determine what to build by asking questions. to-spec is the closing phase—it does not ask questions, but directly synthesizes what has already been clarified into a publishable specification document. The typical sequence is to first use brainstorming to fully explore the approach, then use to-spec to capture the conclusions in a spec and publish it to the issue tracker.

What needs to be prepared before using to-spec?

The project must already have an issue tracker configured along with a triage label glossary. These should already be provided to you. If not, to-spec will prompt you to first run /setup-matt-pocock-skills to complete the configuration. It also needs to be able to read the codebase, as it explores the repository first to understand its current state.

What sections does a spec generated by to-spec contain?

Seven sections: problem statement (describing the problem from the user’s perspective), solution (describing the solution from the user’s perspective), user stories (an extensive numbered list covering all aspects of the feature), implementation decisions (modules to create or modify, interface and schema changes, API contracts, etc.), testing decisions (criteria for good tests, modules to test, and comparable tests to reference), out-of-scope notes, and additional notes.

What is a test seam, and why does the spec need a dedicated section for it?

A test seam is the point at which you test a feature. to-spec follows three principles: existing seams take precedence over new seams, seams should be as high-level as possible, and the total number of seams should be minimized. The spec documents these decisions and confirms the seam selection with you before writing it, because if the seam is chosen incorrectly, all subsequent tests will be built at the wrong level.

Can to-spec be triggered automatically?

No. This skill is configured with disable-model-invocation: true, so the model will not invoke it on its own. You must manually trigger it with /to-spec. This design prevents the AI from rushing to generate documentation before the discussion is fully clarified.