/write-spec — Feature Specification

Writing rule

Use the controlled technical writing profile from .claude/rules/writing-standard.md for each artifact. Use short complete sentences, active voice, one term for one meaning, and clear lists.

Write a feature specification or product requirements document (PRD).

Activated role

When /write-spec runs, activate the Product Manager role — they own PRD creation, user stories, and acceptance criteria. For roadmap-level prioritisation calls, escalate to the Head of Product.

Design-heavy features should also involve the UX Designer (for user flows) and the UI Designer (for component specs) once the PRD has a problem statement. Technical feasibility review happens at the Tech Design phase, not here — the /write-spec output hands off to the Tech Lead who activates for Phase 2.

See .claude/rules/role-triggers.md for the full activation protocol.

Usage

/write-spec SSO support for enterprise
/write-spec Users want to export data as CSV
/write-spec We need better onboarding

Workflow

1. Understand the Feature

Accept any of: a feature name, a problem statement, a user request, or a vague idea.

2. Gather Context

Ask conversationally:

• User problem — what problem does this solve? Who experiences it?
• Target users — which user segment(s)?
• Success metrics — how will we know this worked?
• Constraints — technical, timeline, dependencies?
• Prior art — has this been attempted before?

3. Pull Context from Connected Tools

If the project has integrations available:

• GitHub Issues (the default tracker) — search for related issues, epics, or features in the project's repo. Teams using other trackers (Linear, Jira) can substitute the equivalent search.
• Notion / Confluence — search for related research, specs, or design docs
• Figma — pull related mockups or wireframes

4. Generate the PRD

Resolve the PRD template via the portfolio helper so adopter overrides win when present:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
template=$(portfolio_resolve_template prd.md)   # → custom-templates/prd.md if present, else templates/prd.md

Single-fork adopters (no portfolio block) and adopters with no override fall straight through to templates/prd.md. Adopters who want a customised PRD shape drop their version at <private_repo>/custom-templates/prd.md. See templates/README.md for the path-mirroring convention.

Read .claude/rules/writing-standard.md before drafting. Treat the resolved template as the source of truth: keep required sections, remove empty conditional sections, replace unknown required values with TBD, and delete the guidance comment before filing.

The PRD should include:

# {Feature Name} — PRD

## Problem Statement
## Goals
   3–5 specific, measurable outcomes

## Non-Goals
   3–5 things explicitly out of scope

## User Stories
   As a [user type], I want [capability] so that [benefit]

## Requirements
### Must-Have (P0)
### Nice-to-Have (P1)
### Future (P2)

## Success Metrics
### Leading Indicators (days–weeks)
### Lagging Indicators (weeks–months)

## Open Questions
## Timeline

The list above is illustrative. Use the resolved template's Required and Conditional guidance. Do not add an empty conditional section only because it appears in this example.

5. Review and Iterate

After generating the draft: ask if sections need adjustment, offer follow-ups.

6. Create the Tracking Ticket

Offer to create an epic / feature ticket in the team's tracker with the PRD content.

---

Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.