PRD Breakdown - Analyze and Decompose Product Requirements

Analyze a Product Requirements Document (PRD) and decompose it into atomic features that integrate with the claude-harness workflow.

Arguments: $ARGUMENTS

Phase 0: PRD Input Detection & Storage

1. Detect PRD source (in priority order):
   • If arguments start with @ -> treat as file reference (e.g., @./docs/prd.md)
   • Else if --url flag provided -> fetch from GitHub issue
   • Else if --file flag provided -> read from specified file path
   • Else if file ./.claude-harness/prd.md exists -> read from file
   • Else if arguments provided -> treat as inline PRD markdown
   • Else -> prompt user for interactive input
2. Validate PRD format:
   • Check minimum length (at least 100 characters of content)
   • If Markdown: verify structure (sections, requirements)
   • If plain text: parse as-is
   • If too large (>100KB): warn user, ask to focus on specific sections
3. Store PRD input:
   • Create .claude-harness/prd/ directory if missing
   • Save PRD content to .claude-harness/prd/input.md
   • Create .claude-harness/prd/metadata.json:

     {
       "version": 1,
       "sourceType": "inline|file|github|interactive",
       "fetchedAt": "{ISO timestamp}",
       "sourceUrl": "{URL or path}",
       "hash": "{SHA256 of PRD}",
       "characterCount": 0,
       "sections": 0
     }

Phase 1: PRD Analysis

Perform comprehensive analysis from three perspectives:

4. Product Analysis:
   • Extract business goals, user personas, functional requirements
   • Identify non-functional requirements, dependencies, constraints
5. Architecture Analysis:
   • Review feasibility and technical complexity
   • Propose implementation order (dependency graph)
   • Identify risks and mitigations
   • Suggest MVP features
6. QA Analysis:
   • Define acceptance criteria for each requirement
   • Identify edge cases and error scenarios
   • Specify performance/security requirements
7. Save analysis results to .claude-harness/prd/analysis.json:

   {
     "version": 1,
     "analyzedAt": "{timestamp}",
     "product": {
       "businessGoals": [...],
       "userPersonas": [...],
       "functionalRequirements": [...]
     },
     "architecture": {
       "feasibilityAssessment": [...],
       "implementationOrder": [...],
       "mvpFeatures": [...],
       "dependencies": {...}
     },
     "qa": {
       "verificationFramework": {...},
       "edgeCases": [...]
     }
   }

Phase 2: Breakdown Generation

8. Transform analysis into atomic features:
   • For each functional requirement (from product analysis):
     • Generate feature name (readable title)
     • Extract acceptance criteria (from QA analysis)
     • Determine complexity from architecture assessment
     • Identify dependencies
     • Assign risk level
9. Resolve dependencies:
   • Build dependency graph: feature A depends on B, B depends on C
   • Topologically sort (ensures dependencies implemented first)
   • Detect cycles: ERROR if circular dependency found
   • Generate priority ordering
10. Generate feature specifications (with structured Gherkin acceptance criteria):

    {
      "id": "feature-XXX",
      "prdSource": {
        "section": "Section Name",
        "requirement": "R001"
      },
      "name": "Feature Title",
      "description": "One-line description",
      "detailedDescription": "Full description from PRD",
      "priority": 1,
      "dependencies": ["feature-YYY"],
      "acceptanceCriteria": [
        {
          "scenario": "Descriptive scenario name",
          "given": "precondition (context setup)",
          "when": "action performed",
          "then": "expected outcome"
        }
      ],
      "riskLevel": "low|medium|high",
      "estimatedComplexity": "low|medium|high",
      "mvpFeature": true|false
    }

    Important: acceptanceCriteria MUST use structured Gherkin format ({ scenario, given, when, then }) -- not plain strings. This enables the ATDD workflow in /flow --team where the tester teammate programmatically iterates scenarios to write executable tests.
11. Apply limits (if --max-features N provided):
    • Sort by priority, keep top N
    • Summarize excluded features

Phase 3: Feature Review & Creation

12. Generate preview showing (skip if --auto flag provided):

    • Total PRD sections analyzed
    • Functional requirements extracted
    • Features to create (grouped by priority)
    • MVP features highlighted
    • Risk assessment summary

    PRD BREAKDOWN ANALYSIS COMPLETE
    Sections: 5 | Requirements: 23 | Features: 8
    MVP Features: 3 | High-Risk: 1 | Dependencies: 5
    
    FEATURES (by priority):
      1. [MVP] Add user authentication
         Risk: MEDIUM | Complexity: MEDIUM | No dependencies
    
      2. Build user dashboard
         Risk: LOW | Complexity: LOW | Depends on: #1
      ... (6 more)
    
    Create features? [Y/n/select/review]

13. Handle user response:
    • Y: Create all features (go to step 14)
    • n: Stop here, show file path: .claude-harness/prd/breakdown.json
    • select: Show multi-select menu, create only selected features
    • review: Display full breakdown details for inspection
14. Create features in .claude-harness/features/active.json:
    • For each selected feature:
      • Generate next sequential feature ID (read active.json, find max, increment)
      • Add feature entry with full PRD metadata:

        {
          "id": "feature-XXX",
          "name": "...",
          "description": "...",
          "priority": N,
          "status": "pending",
          "acceptanceCriteria": [
            {
              "scenario": "...",
              "given": "...",
              "when": "...",
              "then": "..."
            }
          ],
          "prdMetadata": {
            "section": "...",
            "breakdown": "prd-{date}-{hash}"
          },
          "verification": {
            "build": "{auto-detected}",
            "tests": "{auto-detected}",
            "lint": "{auto-detected}",
            "typecheck": "{auto-detected}"
          },
          "relatedFiles": [],
          "github": {
            "issueNumber": null,
            "prNumber": null,
            "branch": "feature/feature-XXX"
          },
          "createdAt": "{timestamp}",
          "updatedAt": "{timestamp}"
        }

Phase 3.5: GitHub Issue Creation (unless --no-issues)

GitHub issues are created by default for all generated features. Skip with --no-issues.

15. Pass 1 -- Create issues with rich bodies (in dependency order -- dependencies first):

    • Use the cached GitHub owner/repo from the session context (parse git remote get-url origin only if absent)

    • For each created feature (ordered so dependencies are created first):

      1. Build labels:
         • Base: ["feature", "prd-generated", "claude-harness"]
         • If mvpFeature is true: add "mvp"
         • If riskLevel is "high": add "high-risk"
      2. Build rich issue body:

         ## Description
         
         {feature.detailedDescription or feature.description}
         
         ### PRD Source
         **Section:** {prdSource.section} | **Requirement:** {prdSource.requirement}
         
         ---
         
         ## Acceptance Criteria
         
         **Scenario: {scenario}**
         - **Given** {given}
         - **When** {when}
         - **Then** {then}
         
         {repeat for each criterion in acceptanceCriteria}
         
         ---
         
         ## Implementation Context
         
         | Attribute | Value |
         |-----------|-------|
         | Priority | {priority} |
         | Complexity | {estimatedComplexity} |
         | Risk Level | {riskLevel} |
         | MVP Feature | {mvpFeature ? "Yes" : "No"} |
         
         ### Related Files
         {for each file in relatedFiles: "- `{file}`"}
         {if empty: "- To be determined during planning"}
         
         ### Implementation Hints
         {from architecture analysis for this feature: suggested approach, tech stack considerations, risks and mitigations}
         
         ---
         
         ## Dependencies
         
         {placeholder -- will be updated in Pass 2 with actual issue numbers}
         {if feature.dependencies: "Depends on: {list dependency feature names}"}
         {if no dependencies: "No dependencies -- can be implemented independently."}
         
         ---
         
         ## Verification Commands

         build: {verification.build or "not configured"} tests: {verification.tests or "not configured"} lint: {verification.lint or "not configured"} typecheck: {verification.typecheck or "not configured"} acceptance: {verification.acceptance or "not configured"}

         
         ---
         *Generated by [claude-harness](https://github.com/panayiotism/claude-harness) PRD breakdown*
         *Breakdown ID: {prdMetadata.breakdown}*

      3. Create issue via gh issue create --title "{feature.name}" --body "{rich body}" --label "{labels}":
         • Handle failures gracefully (log warning, continue with other features)
      4. Update feature entry in active.json:
         • Set github.issueNumber to created issue number
         • Save updated .claude-harness/features/active.json

15.5. Pass 2 -- Update issues with cross-references (after ALL issues are created):

Now that every feature has an assigned `github.issueNumber`, update each issue that has dependencies or is depended upon:

- For each feature with `dependencies` array OR that appears in another feature's `dependencies`:

  1. **Build "Depends on" section**:
     ```markdown
     **Depends on:**
     - #43 -- Add user authentication
     - #45 -- Create database schema
     ```
     Map each dependency feature ID to its `github.issueNumber` and `name`.

  2. **Build "Blocks" section** (reverse lookup):
     - Find all features whose `dependencies` array includes this feature's ID
     ```markdown
     **Blocks:**
     - #44 -- Build user dashboard
     - #46 -- Add admin panel
     ```

  3. **Replace the Dependencies section** in the issue body:
     - Use `gh issue edit {issueNumber} --body "{updated body}"`
     - Replace the placeholder dependency section with the actual cross-referenced version

This ensures **bidirectional linking**: if feature-002 depends on feature-001, then:
- feature-001's issue shows "**Blocks:** #44 -- feature-002 name"
- feature-002's issue shows "**Depends on:** #43 -- feature-001 name"

**Error Handling** (applies to both Pass 1 and Pass 2):
- `gh` unavailable or unauthenticated (`gh auth status` fails) -> Log warning, skip issue creation entirely but continue with feature creation
- Permission denied -> Log error for specific feature, continue with others
- API rate limit (rare below ~50 issues) -> back off and retry the failed call
- Network error -> Retry 3x with exponential backoff
- Pass 2 update failure -> Log warning (issues exist but without cross-references), continue

Phase 4: Summary & Next Steps

16. Report completion:

    FEATURES CREATED FROM PRD
    PRD Sections: 5
    Features Extracted: 8
    Created Now: 3
    
    GitHub Issues Created: 3
      #43: Add user authentication (MVP)
      #44: Build user dashboard -> depends on #43
      #45: Create database schema
    Cross-references: 2 issues updated with dependency links
    
    Files:
    - PRD input: .claude-harness/prd/input.md
    - Analysis: .claude-harness/prd/analysis.json
    - Breakdown: .claude-harness/prd/breakdown.json
    
    NEXT STEPS:
    1. Start implementation: /flow feature-001
    2. Or batch process: /flow --autonomous
    3. Review analysis: cat .claude-harness/prd/breakdown.json

17. Interactive menu (if user doesn't select all):
    • Use AskUserQuestion with multi-select: true
    • Show pending features from breakdown
    • Allow user to start implementing any features

Command Options

Flags

--no-issues

• Skip GitHub issue creation. Features are still created in active.json.
• Useful when GitHub integration is not configured or not needed.
• By default, issues are always created alongside features.

--analyze-only

• Run PRD analysis without creating features
• Useful for review before committing to features

--auto

• Skip feature review confirmation prompt
• Create all extracted features and GitHub issues automatically

--max-features N

• Limit feature creation to top N features by priority
• Useful for phased rollout

Usage Examples

/claude-harness:prd-breakdown "Detailed PRD markdown here..."           # Inline PRD (creates features + issues)
/claude-harness:prd-breakdown @./docs/prd.md                           # File reference (creates features + issues)
/claude-harness:prd-breakdown --file ./docs/prd.md                     # File flag
/claude-harness:prd-breakdown --url https://github.com/.../issues/42  # GitHub issue as PRD source
/claude-harness:prd-breakdown --analyze-only                           # Analysis only (no features, no issues)
/claude-harness:prd-breakdown --auto                                   # No prompts, full automation
/claude-harness:prd-breakdown --max-features 10                        # Top 10 only
/claude-harness:prd-breakdown @./prd.md --no-issues                   # Features only, skip GitHub issues
/claude-harness:prd-breakdown @./prd.md --auto                        # Full automation: analyze + features + issues

Syntax Variations

Error Handling

Integration with Other Commands

• With /flow: Each created feature can be implemented via /flow feature-XXX
• With /start: Shows PRD analysis summary from prior sessions
• With memory: Records decomposition patterns to procedural memory for future PRDs