This skill takes the current conversation context and understanding of the codebase and produces a spec. Do not interrogate the user—just synthesize what you already know.
The issue tracker and triage label vocabulary should already have been provided to you—if not, tell the user to run /setup-matt-pocock-skills。
Process
-
If you haven't explored it yet, explore the repo first to understand the current state of the codebase. Use the project's domain glossary terms throughout the spec, and respect any ADRs for the areas you're touching.
-
Sketch out the seams at which you will test this feature. Existing seams should be preferred over new seams. Use the highest possible seam. If a new seam is needed, propose it at the highest point you can reach. The fewer seams in the codebase, the better—the ideal number is one.
Confirm with the user that these seams match their expectations.
-
Write the spec using the template below, then publish it to the project's issue tracker. Add the
ready-for-agenttriage label—no further triage is needed.
Problem Statement
The problem the user is facing, described from the user's perspective.
Solution
The solution to the problem, described from the user's perspective.
User Stories
A long, numbered list of user stories. Each user story follows this format:
- As a <role>, I want <feature>, so that <benefit>
This list of user stories should be extremely detailed, covering every aspect of the feature.
Implementation Decisions
A list of implementation decisions that have been made. It can include:
- The modules to be built/modified
- The interfaces of those modules that will be modified
- Technical clarifications from the developer
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions
Do not include specific file paths or code snippets. They may become outdated quickly.
Exception: if the prototype produced a snippet that encodes a decision more precisely than prose (state machine, reducer, schema, type shape), inline it into the relevant decision and briefly note that it came from the prototype. Trim to the decision-dense parts—not a runnable demo, just the important snippets.
Testing Decisions
A list of testing decisions that have been made. Include:
- A description of what makes a good test (test only external behavior, not implementation details)
- Which modules will be tested
- Precedents for testing (i.e. similar types of tests in the codebase)
Out of Scope
A description of what is out of scope for this spec.
Further Notes
Any further notes about the feature.