This skill takes the current conversation context and understanding of the codebase to produce a spec. Do not interrogate the user — only synthesize what you already know.
The issue tracker and category label vocabulary should have been provided to you — if not, run
/setup-matt-pocock-skills
.
Process
-
If you haven't explored it yet, first explore the repository to understand the current state of the codebase. Use the project's domain glossary terms throughout the spec, and respect any ADRs in the areas you are touching.
-
Outline the seams where you will test the feature. Existing seams should take precedence over new seams. Use the highest possible seams. If new seams are needed, propose them at the highest point you can achieve. The fewer seams in the codebase, the better — ideally one.
Confirm with the user that these seams meet their expectations.
-
Write the spec using the template below, then publish it to the project's issue tracker. Apply the
category label — no further categorization is needed.
<spec-template>
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 the format:
- As a <role>, I want <feature> so that <benefit>
<user-story-example>
1. As a mobile banking customer, I want to see my account balance so that I can make more informed spending decisions
</user-story-example>
This list of user stories should be extremely detailed, covering all aspects of the feature.
Implementation Decisions
A list of implementation decisions made. This can include:
- Modules to be built/modified
- Interfaces of those modules that will be modified
- Technical clarifications from developers
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions
Do not include specific file paths or code snippets. They can quickly become outdated.
Exception: If a prototype produces a snippet (state machine, reducer, schema, type shape) that encodes a decision more precisely than prose, inline it into the relevant decision and briefly note that it comes from a prototype. Cut to the decision-dense parts — not a runnable demo, just the important snippets.
Testing Decisions
A list of testing decisions made. Include:
- A description of what constitutes a good test (test only external behavior, not implementation details)
- Which modules will be tested
- Testing precedents (i.e., similar types of tests in the codebase)
Out of Scope
A description of content outside the scope of this spec.
Additional Notes
Any additional notes about the feature.
</spec-template>