outcomeengineering/decomposing-prd-to-capabilities

<objective> Transform Product Requirements (PRD) into well-scoped Capability specs. Each capability represents what the product CAN DO—a large, cross-cutting vertical slice of functionality. </objective> <prerequisite> **READ FIRST**: `/understanding-outcome-decomposition`

You must understand:

• Capability = what the product CAN DO (cross-cutting vertical slice)
• Capabilities may span many customer journeys
• The tree can start small (1 capability) and grow organically

</prerequisite>

<quick_start>

1. Read the PRD completely
2. Identify what the product should be CAPABLE of doing
3. Each capability is a cross-cutting area, not a customer journey
4. Create capability specs with BSP numbering based on dependencies
5. Start small—a single capability is valid

</quick_start>

<workflow>

Step 1: Analyze PRD for Product Abilities

Read the PRD and ask: "What should this product be CAPABLE of doing?"

| Look for | Examples | | ------------------------ | ---------------------------------------------- | | Core functionality areas | "Generate documents", "Manage user identities" | | Cross-cutting concerns | "Analytics", "Notifications", "Audit logging" | | Infrastructure needs | "Test harness", "CLI tooling" | | Integration points | "Third-party API integration", "Export/import" |

Step 2: Identify Capability Boundaries

A capability is what the product CAN DO.

Examples of good capability names:

• "Document Generation"
• "Custody Account Management"
• "Monetization Platform"
• "Identity and Authentication Management"
• "SPI Peripheral Support" (for hardware library)

NOT capabilities:

• "User logs in and sees dashboard" (customer journey, not product ability)
• "Parse configuration file" (too small—story or feature level)
• "Sprint 1 work" (timeline, not functionality)

Step 3: Consider Starting Small

A single capability is valid. The tree grows organically.

spx/
├── product.prd.md
└── 21-core.capability/         ← Start with one
    └── 21-first-feature.feature/
        └── 21-first-story.story/

Later, you might add:

spx/
├── product.prd.md
├── 13-test-infrastructure.capability/  ← Discovered dependency
├── 21-core.capability/
└── 54-advanced.capability/             ← Added as product grows

Step 4: Determine BSP Ordering

Lower BSP = dependency. Order by what depends on what.

| Pattern | BSP Strategy | | -------------------------------------- | ------------------- | | Infrastructure (test harness, tooling) | Low BSP (10-20) | | Core functionality | Mid BSP (21-50) | | Advanced/optional features | High BSP (54-80) | | Improvements/polish | Highest BSP (76-99) |

BSP Calculation

| Scenario | Formula | Example | | ------------------------ | --------------------- | ------------------------- | | First capability | 21 | 21-core.capability/ | | Insert before 21 | floor((10+21)/2) = 15 | 15-infra.capability/ | | Insert between 21 and 54 | floor((21+54)/2) = 37 | 37-new.capability/ | | Append after 54 | floor((54+99)/2) = 76 | 76-advanced.capability/ |

Parallel Capabilities (Same BSP)

Capabilities with the same BSP can be worked on in parallel:

37-users.capability/      ← Same BSP = parallel
37-billing.capability/    ← Same BSP = parallel
37-reports.capability/    ← Same BSP = parallel

Step 5: Write Capability Specs

For each capability, create:

spx/NN-{slug}.capability/
├── {slug}.capability.md
└── tests/                 # Created when starting implementation

Capability Spec Structure

Use the template from /managing-spx:

# Capability: {Name}

## Purpose

{What this product ability delivers and why it matters to users}

## Success Metric

- **Baseline**: {Current state}
- **Target**: {Expected improvement}
- **Measurement**: {How to track}

## Requirements

{Prose from PRD, focused on this capability's scope}

## Test Strategy

{Overview of how this capability will be tested—can span multiple levels}

## Outcomes

{Capability-level outcomes, if any—remember Principle 11}

## Architectural Constraints

{ADRs and PDRs that constrain this capability}

Note on Outcomes: A capability may have its own outcomes (high-level integration/E2E scenarios) OR it may have no direct outcomes—just features underneath. Both are valid.

Step 6: Validate Decomposition

For each capability:

□ Represents what the product CAN DO
□ Is a coherent cross-cutting area
□ Has clear boundaries with other capabilities
□ BSP reflects actual dependencies
□ Can be decomposed into ≤9 features (if needed now)

</workflow> <examples>

Example 1: SPI Library PRD → Capabilities

PRD excerpt:

"Hardware engineers need to configure SPI peripherals, generate Verilog, and verify on real FPGAs."

Analysis:

| Product ability | Capability? | | ------------------------ | --------------------------------------------- | | "SPI Peripheral Support" | YES - what the library CAN DO | | "Code Generation" | YES - distinct ability | | "FPGA Verification" | MAYBE - could be part of code gen or separate |

Possible structures:

Option A: Start small

spx/
├── spi-library.prd.md
└── 21-spi-peripherals.capability/

Option B: Separate concerns

spx/
├── spi-library.prd.md
├── 13-test-infrastructure.capability/
├── 21-spi-peripherals.capability/
└── 54-fpga-verification.capability/

Both are valid. Start with A, grow to B as needed.

Example 2: Auth System PRD → Capabilities

PRD excerpt:

"Users need to register, log in, reset passwords, and manage their profiles. Support OAuth and magic links."

Analysis:

This is ONE capability: "Identity and Authentication Management"

spx/
├── auth-system.prd.md
└── 21-identity-auth.capability/
    ├── 21-registration.feature/
    ├── 37-login.feature/
    ├── 54-password-reset.feature/
    └── 76-oauth.feature/

NOT separate capabilities for login, registration, etc.—those are features.

Example 3: E-commerce Platform PRD → Capabilities

PRD excerpt:

"Customers browse products, add to cart, checkout with payment, track orders."

Analysis:

| Product ability | Capability | | ------------------ | ---------------------------- | | Product catalog | 21-catalog.capability/ | | Shopping cart | 37-cart.capability/ | | Payment processing | 37-payment.capability/ | | Order fulfillment | 54-fulfillment.capability/ |

Note: cart and payment are parallel (same BSP)—neither depends on the other.

</examples>

<anti_patterns>

What NOT to Create as Capabilities

| Anti-pattern | Why wrong | Correct level | | --------------------- | --------------------------- | --------------------- | | "User Login" | Too small | Feature | | "Parse Config" | Too small | Story | | "Sprint 1" | Timeline, not functionality | Not a container | | "Customer Journey X" | Journey, not ability | May span capabilities | | "API Endpoint /users" | Implementation detail | Story |

Signals You're at Wrong Level

| Signal | Problem | | ---------------------------------- | ------------------------------ | | Capability name is a verb phrase | Might be a feature or story | | Capability fits in 1-2 features | Might be too small | | Capability name includes "and" | Might be multiple capabilities | | Can't identify what product CAN DO | Needs clarification |

</anti_patterns>

<success_criteria>

Decomposition complete when:

• [ ] Each capability represents what the product CAN DO
• [ ] Capabilities are cross-cutting vertical slices
• [ ] BSP ordering reflects dependencies
• [ ] Structure can grow organically (start small is OK)
• [ ] No capability is really a feature or story in disguise

</success_criteria>