| name | forge-decompose-prd |
| description | Decompose an existing monolithic Product Requirements Document (PRD) into a Product Vision document and individual Feature documents. Use this skill when you want to break a large PRD into independent, self-contained features that can be prioritized, built, and delivered separately.
|
Skill: Decompose a PRD into Product Vision and Features
You are a product requirements analyst specializing in decomposition and modularization. Your job is to split a monolithic PRD into a Product Vision document (cross-cutting concerns) and individual Feature documents (self-contained units of work), each with user stories, requirements, acceptance criteria, and implementation tasks.
The original PRD is preserved - this skill produces new documents alongside it.
When to Use This Skill
Use when:
- A monolithic PRD has 15+ functional requirements or 3+ implementation phases
- The team wants to prioritize, reorder, or deliver features independently
- Multiple agents will work on different areas in parallel
- You want clearer traceability between user stories, requirements, and tasks
Don't use when:
- The PRD is small (under 10 requirements, 1–2 phases) - stay monolithic
- You need to add one new feature to an existing project - use
forge-build-feature-prd
- No PRD exists yet - use
forge-build-prd first
Process
Step 1: Locate and Analyze the PRD
Find the PRD at docs/PRD.md (or docs/spec.md). Read the entire document and build a mental model of:
Cross-cutting concerns (span all features):
- Sections 1 (Overview), 3 (Goals/Non-Goals), 4.1 (Personas), 5 (Research), 7 (Technical Architecture), 9 (NFRs), 10 (Security), 11 (Accessibility), 13 (System States), 16 (Analytics), 18 (Dependencies/Risks), 19 (Future), 21 (Glossary)
Feature-specific content (groupable):
- Sections 4.2 (User Stories), 8 (Functional Requirements), 12 (UI/Interaction), 14 (Phases), 15 (Testing), 17 (Acceptance Criteria)
Feature boundaries - natural groupings based on shared personas, components, subsystems, UI flows, or phases.
Step 2: Identify Features
Group feature-specific content into distinct, self-contained features. Each feature should:
- Be describable in one sentence
- Contain 2–8 functional requirements (split if more)
- Have at least one user story
- Be independently implementable (possibly with declared dependencies)
- Map to one or more PRD phases
| Signal | Indicates |
|---|
| Related user stories for same persona | One feature |
| Distinct UI screen or workflow | One feature |
| Subsystem with clear inputs/outputs | One feature |
| Requirements referencing same files/components | One feature |
| Self-contained implementation phase | One feature |
| Foundational phase (setup/scaffolding) | "Foundation" feature |
Naming: lowercase-hyphenated filenames (authentication.md). Unique ID prefixes (3–5 chars) derived from feature name (AUTH, SRCH, DASH).
Step 3: Present the Decomposition Plan
Before writing any documents, present and get user approval:
## Proposed Decomposition
**Product Vision** - Cross-cutting concerns extracted from the PRD
**Features identified:**
| # | Feature | ID Prefix | User Stories | Requirements | Dependencies |
|---|---------|-----------|-------------|-------------|-------------|
| 1 | [Name] | [PREFIX] | US-01, US-02 | FR-01, FR-03 | None |
| 2 | [Name] | [PREFIX] | US-03 | FR-04–FR-06 | Feature 1 |
**Dependency graph:**
Feature 1 → Feature 2, Feature 3 (parallel)
Feature 2 + Feature 3 → Feature 4
Ask: "Does this grouping make sense? Should features be merged or split? Are dependencies correct?"
Step 4: Write the Product Vision Document
Create docs/product-vision.md. Load references/product-vision-template.md for the full structure. Extract content from the original PRD's cross-cutting sections.
Step 5: Write the Feature Documents
For each feature, create docs/features/{feature-name}.md. Load references/feature-document-template.md for the full structure. Map original PRD content:
- User stories → re-ID with feature prefix (
AUTH-US-01)
- Functional requirements → re-ID with feature prefix (
AUTH-FR-01)
- Implementation tasks → scoped to this feature only
- Preserve a traceability table mapping new IDs back to original PRD IDs
Step 6: Validate the Decomposition
Run this checklist before finalizing:
If any checkbox fails, fix the issue before proceeding.
Step 7: Present the Result
Summarize with a table of features, their files, counts, dependencies, and suggested order. Point to next steps: review → forge-build-agent-team → project-orchestrator Execute all features.
Gotchas
- FT- prefix collision. The
FT- prefix is reserved for post-project Feature PRDs. Never assign FT- as a feature ID prefix during initial decomposition.
- Cross-cutting contamination. It's tempting to put NFRs or security requirements in feature documents. Don't. If a requirement applies to multiple features, it belongs in the product vision.
- Circular dependencies. Walk the full dependency graph before finalizing. A→B→C→A is a bug. Present the graph as a tree so the user can verify.
- Nothing should be lost. After decomposition, the union of all feature requirements MUST equal the original PRD's requirements. Double-check counts.
- Preserve the original PRD. Never modify or delete
docs/PRD.md. The decomposition produces new documents alongside it.
Guidelines
- Preserve the original PRD. New documents live alongside it - never modify or replace.
- Don't duplicate cross-cutting concerns. NFRs, security, accessibility, architecture, and tech stack live in the product vision only. Feature documents reference it.
- Keep features independent. Merge features that are too tightly coupled to separate.
- Declare dependencies explicitly. The orchestrator uses these declarations to determine execution order.
- Maintain traceability. Every feature document maps new IDs back to original PRD IDs.
- Foundation features are valid. Project scaffolding can be a feature rather than a cross-cutting concern.
