panayiotism/claude-harness/prd-breakdown

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

1. 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

1. 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:

1. Product Analysis:

• Extract business goals, user personas, functional requirements
• Identify non-functional requirements, dependencies, constraints

1. Architecture Analysis:

• Review feasibility and technical complexity
• Propose implementation order (dependency graph)
• Identify risks and mitigations
• Suggest MVP features

1. QA Analysis:

• Define acceptance criteria for each requirement
• Identify edge cases and error scenarios
• Specify performance/security requirements

1. 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

1. 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

1. 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

1. 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.

1. Apply limits (if --max-features N provided):

• Sort by priority, keep top N
• Summarize excluded features

Phase 3: Feature Review & Creation

1. 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

1. Build user dashboard

Risk: LOW | Complexity: LOW | Depends on: #1 ... (6 more)

Create features? [Y/n/select/review] ```

1. 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

1. 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.

1. 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"

1. 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

### 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} ```

1. Create issue via gh issue create --title "{feature.name}" --body "{rich body}" --label "{labels}":

• Handle failures gracefully (log warning, continue with other features)

1. 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`.

1. 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

```

1. 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

1. 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