PM Spec Writing
Take an idea (often vague) and turn it into a specification a developer or AI agent can actually build from. Stack-agnostic. Works for new features, bug fixes, content changes, or infrastructure work.
When to use
- Translating an idea into a buildable feature spec
- Writing a PRD or product requirement document
- Filing a bug report that someone else can act on
- Scoping a project before kickoff
- Prioritizing a backlog of feature requests
- Writing acceptance criteria for an existing feature
- Breaking a large initiative into shippable increments
When NOT to use
- Quarterly or annual planning across multiple initiatives (use
roadmap-planning)
- Code review or debugging existing code (use
code-review-web)
- Design decisions for a feature already specced (use
design-standards)
- User research to validate an idea (use
ux-research)
Required inputs
- The idea, request, or problem being addressed
- The audience or user affected
- Any existing constraints (stack, deadlines, dependencies)
- The success metric (how will you know it worked?)
If the idea is vague, the workflow's first step is clarification. Do not write specs around vagueness.
The framework: 4 phases
Every PM workflow follows the same arc. The phases are universal even if the specific outputs vary.
Phase 1: Clarify the idea
Before any spec, answer four questions. If any answer is "I don't know," go back to the user.
- What user problem does this solve? Not "what does it do." The problem comes first; the feature is the proposed solution.
- Who specifically benefits? Be precise. "Users" is not specific. "First-time visitors who don't convert" is.
- What is the success metric? How will you know it worked? Pick one primary metric.
- Why now? What changed that makes this the right time to build it? If "nothing changed," it might not be the right time.
Phase 2: Scope by impact and effort
Plot every candidate idea on the impact/effort grid:
HIGH IMPACT / LOW EFFORT Ship immediately
Examples: copy fixes, contrast fixes, meta tags,
broken links, missing alt text, redirects
HIGH IMPACT / HIGH EFFORT Plan and batch
Examples: new page type, new feature, schema overhaul,
major redesign, new integration
LOW IMPACT / LOW EFFORT Nice-to-have batch
Examples: tooltip improvements, minor copy polish,
cosmetic UX touches
LOW IMPACT / HIGH EFFORT Skip or defer indefinitely
Examples: rebuilding what already works, exotic
edge case features, premature optimization
This is not a perfect framework. Some "low impact" things are mandatory (compliance, accessibility, security). Note exceptions.
Phase 3: Write the spec
Three formats based on the type of work.
Format A: Feature spec (for new features)
TITLE: [Specific, action-oriented]
PROBLEM
[1-2 sentences. The user problem and current state.]
USERS
[Who specifically benefits. Be precise about the user segment.]
PROPOSAL
[1 paragraph. The proposed solution. Stay at the conceptual level.]
USER STORIES
- As a [user type], I want to [action], so that [outcome]
- As a [user type], I want to [action], so that [outcome]
ACCEPTANCE CRITERIA
- Given [context], when [action], then [expected outcome]
- Given [context], when [action], then [expected outcome]
OUT OF SCOPE
[What this spec explicitly does NOT cover. Important for scope control.]
DEPENDENCIES
[Other systems, APIs, designs, content needed before this can ship.]
SUCCESS METRIC
[The one primary metric that tells us this worked. With current baseline if known.]
ESTIMATED EFFORT
[Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (sprints)]
PRIORITY
[P0 launch blocker / P1 next sprint / P2 within quarter / P3 backlog]
Format B: Dev brief (for handing to a developer or AI agent)
For tactical, ready-to-build work. Lighter than a full spec.
CONTEXT: [1-2 sentences explaining why this matters]
TASK: [Specific files, exact changes needed]
CONSTRAINTS: [What must NOT change, what to preserve]
VERIFY: [Exact steps to confirm the work is done correctly]
The verify section is the most-skipped and most-important. Without it, "done" means whatever the implementer thinks done means.
Format C: Bug report
URL or context: [Where it happens]
Symptom: [What the user sees or experiences]
Expected: [What should happen instead]
Steps to reproduce:
1. [Specific step]
2. [Specific step]
3. [Specific step]
Hypothesis: [Likely root cause if known]
Files to investigate: [Likely files involved if known]
Priority:
P0 - blocking critical user flow, ship immediately
P1 - degrades UX significantly, fix this sprint
P2 - minor issue, fix when convenient
P3 - nice-to-have improvement
Browser/device: [If reproducibility might be browser-specific]
Phase 4: Sequence and ship
Specs without sequencing become dust on a shelf.
For a single feature: identify the smallest shippable increment. What is the smallest version that delivers user value? Ship that first. Then iterate.
For a backlog: order by dependencies first, then by priority, then by impact/effort. The order matters more than the priority labels.
Workflow
- Clarify. If the idea is vague, ask the four phase-1 questions before proceeding.
- Scope. Plot the work on the impact/effort grid.
- Pick the right format. Feature spec for new features, dev brief for tactical work, bug report for defects.
- Write the spec. Use the template format. Fill in every section. Empty sections are flags.
- Define done. Verify steps must be unambiguous. "Test it" is not a verify step.
- Get buy-in. Walk through the spec with whoever will build it before they start.
- Sequence. Identify the smallest shippable increment.
Failure patterns
- Specs that describe solutions before problems. Always start with the user problem. The solution is downstream.
- Specs without a success metric. Without a metric, you cannot tell if the feature worked.
- Acceptance criteria that are not testable. "User experience is improved" is not testable. "User completes signup in under 60 seconds" is.
- Specs that include the "how" instead of the "what." Implementation details belong in the dev brief, not the spec. The spec is the desired outcome.
- No "out of scope" section. Without explicit boundaries, scope creeps.
- Bug reports without reproduction steps. Cannot be acted on. Always include steps.
- Verify steps that are vague. "Make sure it works." Useless. Must be specific actions with observable outcomes.
- Skipping the smallest-shippable-increment exercise. Leads to 6-month projects that should have been 2-week experiments.
Output format
Output is one of three formats based on work type, all in markdown:
spec-[feature-name].md for feature specsbrief-[task-name].md for dev briefsbug-[summary].md for bug reports
For larger initiatives, group related specs in a folder:
specs/
initiative-name/
spec-feature-1.md
spec-feature-2.md
brief-task-1.md
README.md (overview and sequencing)
If required data is unavailable
This skill's output depends on data, measurements, or tool results it cannot generate on its own. When a required input, tool, or data source is unavailable or unverifiable, the sanctioned output is the deliverable with the gap stated: what was needed, what was actually obtained or verified, and which parts of the output are affected. Fabricating, estimating, or interpolating a required number to complete the deliverable is never sanctioned. A stated gap is a complete answer.
Reference files