prd-breakdown

What this skill does

# 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`:
     ```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`:
   ```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):
    ```json
    {
      "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:
        ```json
        {
          "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):

    - Parse GitHub owner/repo from `git remote get-url origin` (or use cached from SessionStart)
    - 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**:
         ```markdown
         ## 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 relatedF