What are the four phases?

Clarify the idea (answer what user problem it solves, who specifically benefits, the one success metric, and why now), scope by impact and effort on the impact-effort grid, write the spec in the format that fits the work, then sequence and ship the smallest increment that delivers value. The phases are universal even when the specific output differs across a feature, a bug, or an infrastructure change.

What spec formats does it produce?

Three. A feature spec for new features (problem, users, proposal, user stories, acceptance criteria, out of scope, dependencies, success metric, estimated effort, priority). A dev brief for tactical, ready-to-build work (context, task, constraints, verify). And a bug report for defects (URL or context, symptom, expected, reproduction steps, hypothesis, priority). Pick the lightest format the work actually needs.

Why start with the problem, not the feature?

Because the feature is the proposed solution, and the problem comes first. Specs that describe solutions before problems are a top failure mode: they lock in an answer before anyone has stated the question. Before specifying anything, answer what user problem this solves (not what it does), who specifically benefits (precisely, not 'users'), the one primary success metric, and why now. If the answer to any of those is 'I do not know,' go back and clarify before writing.

Why is the verify section so important?

Because it is the most-skipped and most-important part of a dev brief. Without unambiguous verify steps, 'done' means whatever the implementer thinks done means. 'Test it' or 'make sure it works' is not a verify step; it must be specific actions with observable outcomes, so anyone can confirm the work is correct without guessing at the original intent.

How is this different from roadmap-planning?

PM spec writing turns a single idea, request, or bug into a buildable specification. Roadmap-planning is quarterly or annual planning across multiple initiatives: themes, sequencing, capacity, and trade-offs. Spec one thing here; sequence the whole portfolio there. The two compose: the roadmap names what to build and when, and the spec defines how each item is communicated to the team that builds it.

Skill · PM spec writing

PM spec writing.

Start with the user problem; the feature is downstream.

Take an idea, often vague, and turn it into a specification a developer or AI agent can build from. The work follows four phases: clarify the idea, scope by impact and effort, write the spec in the right format, then sequence and ship. It works for new features, bug fixes, content changes, and infrastructure.

Three formats cover the range: a feature spec for new work, a lighter dev brief for ready-to-build tasks, and a bug report for defects. Every spec starts from the user problem, not the proposed solution.

Audience: PMs, founders, and engineers turning a half-formed idea into a clear brief, filing an actionable bug, or scoping a project before kickoff.

View the skill on GitHub Browse the full catalog

The framework

Four phases, universal across work types.

Every spec follows the same arc, even when the output format changes. The first phase is the one most specs skip.

01Clarify the idea: answer four questions before any spec. What user problem does this solve, who specifically benefits, what is the one success metric, and why now.
02Scope by impact and effort: plot the work on the impact-effort grid. Ship high-impact, low-effort immediately; defer low-impact, high-effort indefinitely. Note compliance and accessibility exceptions.
03Write the spec: pick the format that fits (feature spec, dev brief, or bug report) and fill every section, because an empty section is a flag.
04Sequence and ship: find the smallest increment that delivers user value and ship that first. For a backlog, order by dependencies, then priority, then impact and effort.

Choosing the format

Three formats for three kinds of work.

The format follows the work. Use the heaviest one only when the work warrants it.

01
Feature spec
For new features. Problem, users, proposal, user stories, acceptance criteria, out of scope, dependencies, the one success metric, estimated effort, and priority. Stays at the what, not the how.
02
Dev brief
For tactical, ready-to-build work. Context, task (specific files and changes), constraints (what must not change), and verify (the exact steps to confirm it is done). The verify section is the most-skipped and most-important.
03
Bug report
For defects. URL or context, symptom, expected behavior, numbered reproduction steps, a hypothesis and likely files if known, and a priority from P0 to P3. A bug report without repro steps cannot be acted on.

Reference files

Three references that go alongside the SKILL.md.

references/feature-spec-template.md
The full feature spec template, section by section.
references/dev-brief-template.md
The compact dev brief template for tactical, ready-to-build work.
references/prioritization-frameworks.md
Beyond impact and effort: RICE, weighted scoring, and MoSCoW for scoping a backlog.

Browse all reference files on GitHub

Bridges to other skills

What sits around a single spec.

Spec writing scopes one thing. These cover the planning above it, the validation beside it, and the build after it.

The portfolio above
roadmap-planning
Quarterly and annual planning across many initiatives lives there. Spec writing scopes a single feature, bug, or task into something buildable.
Validate first
ux-research
When the idea's value is unproven, validate it with users before writing the spec. Research answers whether to build; the spec answers what to build.
Design the feature
design-standards
Design decisions for a feature already specced are a design-standards job. The spec sets the outcome; the design works out the interface.
After the build
code-review-web
Reviewing or debugging the code that implements the spec happens there. This skill produces the brief; that skill checks the result.

Open source under MIT

Read the SKILL.md on GitHub.

The skill source lives in the rampstackco/claude-skills repository alongside dozens of other skills covering the full lifecycle of brand and product work. This page is a structured overview; the SKILL.md is the source. MIT licensed.

View SKILL.md Browse the full catalog

Frequently asked questions.

What are the four phases?: Clarify the idea (answer what user problem it solves, who specifically benefits, the one success metric, and why now), scope by impact and effort on the impact-effort grid, write the spec in the format that fits the work, then sequence and ship the smallest increment that delivers value. The phases are universal even when the specific output differs across a feature, a bug, or an infrastructure change.
What spec formats does it produce?: Three. A feature spec for new features (problem, users, proposal, user stories, acceptance criteria, out of scope, dependencies, success metric, estimated effort, priority). A dev brief for tactical, ready-to-build work (context, task, constraints, verify). And a bug report for defects (URL or context, symptom, expected, reproduction steps, hypothesis, priority). Pick the lightest format the work actually needs.
Why start with the problem, not the feature?: Because the feature is the proposed solution, and the problem comes first. Specs that describe solutions before problems are a top failure mode: they lock in an answer before anyone has stated the question. Before specifying anything, answer what user problem this solves (not what it does), who specifically benefits (precisely, not 'users'), the one primary success metric, and why now. If the answer to any of those is 'I do not know,' go back and clarify before writing.
Why is the verify section so important?: Because it is the most-skipped and most-important part of a dev brief. Without unambiguous verify steps, 'done' means whatever the implementer thinks done means. 'Test it' or 'make sure it works' is not a verify step; it must be specific actions with observable outcomes, so anyone can confirm the work is correct without guessing at the original intent.
How is this different from roadmap-planning?: PM spec writing turns a single idea, request, or bug into a buildable specification. Roadmap-planning is quarterly or annual planning across multiple initiatives: themes, sequencing, capacity, and trade-offs. Spec one thing here; sequence the whole portfolio there. The two compose: the roadmap names what to build and when, and the spec defines how each item is communicated to the team that builds it.