Skip to content

[Phase 5] Recursive Decomposition as PRD Stress Test and Technical Spec Generator #421

Description

@frankbria

Summary

Use recursive classify/decompose (inspired by tinyagi/fractals) as a requirements discovery tool — not just for generating tasks, but for stress-testing a PRD and generating a technical specification that surfaces ambiguities before any code gets written.

The Insight

When the LLM recursively decomposes a high-level goal, it will inevitably hit nodes where it can't classify (atomic vs composite) without more information. These ambiguity points are exactly the requirements gaps the PRD should have addressed:

  • "Auth system" → Is this email/password? OAuth? SSO? The PRD doesn't say.
  • "Payment integration" → One provider or multiple? Subscriptions or one-time? The PRD is vague.
  • "Notification system" → Email only? Push? SMS? Real-time? Nobody specified.

These gaps, caught at decomposition time, become questions fed back to the human — turning the recursive decompose into a Socratic refinement loop.

Proposed Workflow

cf prd generate          ← Socratic PRD creation (exists today)
        │
cf prd stress-test       ← NEW: recursive decompose, surface gaps
        │                   Returns: ambiguity questions + draft tech spec
        │
cf prd refine            ← Human answers questions, PRD updated
        │
cf tasks generate        ← Now produces high-quality tasks from refined PRD

The stress-test step is the new primitive. It produces two outputs:

Output 1: Ambiguity Report

Questions the PRD doesn't answer, discovered by trying to decompose:

PRD Stress Test — 7 ambiguities found:

1. AUTH SCOPE (from decomposing "User Authentication")
   The PRD mentions "user accounts" but doesn't specify:
   - Authentication method (email/password? OAuth providers? Both?)
   - Session management approach (JWT? server sessions?)
   → Recommendation: Add "Authentication Requirements" section to PRD

2. DATA PERSISTENCE (from decomposing "Invoice Management")
   The PRD says "store invoices" but doesn't specify:
   - Database choice (relational? document store?)
   - Retention policy (how long? archival?)
   → Recommendation: Add "Data Architecture" section to PRD

3. PAYMENT SCOPE (from classifying "Payment Integration")
   Cannot determine atomicity — depends on:
   - One payment provider or multiple?
   - Subscription billing or one-time payments?
   → Recommendation: Narrow scope in PRD or mark as future phase

Output 2: Draft Technical Specification

The decomposition tree, formatted as a technical spec:

# Technical Specification: Invoice SaaS

## 1. User Authentication
**Scope**: [NEEDS CLARIFICATION — see ambiguity #1]

### 1.1 Email/Password Registration
- User model with email, password_hash, created_at
- Registration endpoint with email verification
- Estimated complexity: Low

### 1.2 Session Management  
- [NEEDS CLARIFICATION: JWT vs server sessions]
- Login/logout endpoints
- Estimated complexity: Low-Medium

## 2. Invoice Management

### 2.1 Invoice CRUD
- Create, read, update, delete invoices
- Line items with quantity, rate, tax
- Draft/Sent/Paid status machine
- Files: models/invoice.py, routes/invoices.py
- Estimated complexity: Medium

### 2.2 PDF Export
- Generate PDF from invoice data
- Template system for invoice layout
- Estimated complexity: Medium
...

Implementation Design

New module: core/stress_test.py

async def stress_test_prd(prd_content: str, max_depth: int = 3) -> StressTestResult:
    """Recursively decompose PRD goals, surface ambiguities."""
    
    goals = extract_high_level_goals(prd_content)  # LLM: what are the major deliverables?
    
    tree = []
    ambiguities = []
    
    for goal in goals:
        node = await recursive_decompose(
            description=goal,
            lineage=[],
            prd_context=prd_content,
            depth=0,
            max_depth=max_depth,
            ambiguities=ambiguities,  # collect gaps as we go
        )
        tree.append(node)
    
    return StressTestResult(
        tree=tree,
        ambiguities=ambiguities,
        tech_spec=render_tech_spec(tree),
    )

Modified classify step

Unlike Fractals' simple binary classify, this version has THREE outcomes:

class Classification(Enum):
    ATOMIC = "atomic"        # Small enough to execute directly
    COMPOSITE = "composite"  # Clearly needs breakdown
    AMBIGUOUS = "ambiguous"  # Can't classify — PRD doesn't specify enough

When the LLM returns AMBIGUOUS, it also returns the question(s) it needs answered. These accumulate into the ambiguity report.

CLI commands

cf prd stress-test                    # Run decomposition against current PRD
cf prd stress-test --max-depth 4      # Deeper analysis
cf prd stress-test --output spec.md   # Write tech spec to file
cf prd stress-test --interactive      # Ask human to resolve ambiguities inline

The --interactive mode is the killer feature: it decomposes, hits an ambiguity, asks the human, records the answer, updates the PRD, and continues decomposing. Essentially a second-pass Socratic session focused on technical feasibility rather than product requirements.

What This Is NOT

  • Not a replacement for cf tasks generate — stress-test produces a spec, not executable tasks
  • Not a replacement for cf prd generate — stress-test refines an existing PRD, doesn't create one
  • Not a planning tool for agents — this is a human-facing discovery tool

Acceptance Criteria

  • cf prd stress-test recursively decomposes PRD goals
  • Ambiguities surfaced with actionable questions
  • Tech spec generated from decomposition tree
  • --interactive mode allows inline ambiguity resolution
  • Resolved ambiguities update the PRD
  • --output writes tech spec to file
  • Max depth prevents runaway recursion (default: 3)
  • Works with PRDs generated by cf prd generate

Dependencies

Relationship to Other Issues

Priority

Phase 5 — this is a refinement that builds on the existing PRD system. Not day-one, but it's a unique differentiator: no other tool in this space helps humans think through what they're building before agents start coding.

Metadata

Metadata

Assignees

No one assigned

    Labels

    architectureSystem architecture and design patternsenhancementNew feature or requestphase-5Phase 5: Advanced Features & Polishphase-5.2Phase 5.2: Quality & Intelligence (PROOF9, PRD stress test, unified config)

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions