decompose

Intent

Break down a complex goal into smaller, manageable subproblems with clear boundaries, dependencies, and acceptance criteria. Enable parallel work and incremental progress.

Success criteria:

• Goal fully decomposed (no gaps)
• Subproblems are independently verifiable
• Dependencies are explicit
• Acceptance criteria are testable
• Decomposition depth is appropriate

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Inputs not listed here are outside the capability's contract: a workflow step that binds them gets W604 (STANDARD v1.1 §5.5).

Procedure

1. Understand the goal: Clarify what needs to be achieved
   • Parse the problem statement
   • Identify success criteria
   • Note implicit requirements
   • Determine scope boundaries
2. Identify major components: Find natural divisions
   • Functional areas
   • Phases or stages
   • User journeys
   • Technical layers
3. Create subproblems: Define each component
   • Clear, specific objective
   • Bounded scope
   • Measurable outcome
   • Independent when possible
4. Define dependencies: Map relationships
   • Which subproblems block others?
   • Which can proceed in parallel?
   • Are there shared resources?
   • Create dependency graph (dependencies, one edge per blocking pair)
5. Add acceptance criteria: Specify done conditions
   • Testable conditions
   • Measurable outcomes
   • Quality requirements
   • Edge case handling
6. Validate completeness: Check coverage
   • Do subproblems cover entire goal?
   • Any gaps or overlaps?
   • Are boundaries clear?
   • Is granularity consistent?
7. Recurse if needed: Decompose large subproblems
   • Check against target granularity
   • Decompose subproblems that are too large
   • Maintain consistent depth
   • Stop when atomic enough

Output Contract

Return a structured object:

decomposition:
  goal: string  # Original goal
  depth: integer  # Levels of decomposition
  total_subproblems: integer
  granularity: epic | story | task
subproblems:
  - id: string
    name: string
    description: string
    parent: string | null  # Parent subproblem ID
    level: integer  # Depth in tree
    dependencies: array[string]
    acceptance_criteria:
      - criterion: string
        testable: boolean
        priority: required | optional
    estimated_effort: string | null
    parallelizable: boolean
structure:  # Problem hierarchy
  goal: string  # Root of the tree
  children:
    - id: string
      name: string
      children: array  # Nested subproblems
dependencies:  # Subproblem dependencies (edges of the DAG)
  - from: string  # Subproblem that must finish first
    to: string  # Subproblem that depends on it
constraints:
  - type: scope | time | resource | technical
    description: string
    affects: array[string]  # Subproblem IDs
gaps:
  - description: string
    suggestion: string
overlaps:
  - subproblems: array[string]
    description: string
    resolution: string
confidence: 0..1
evidence_anchors: ["source:ref"]
assumptions: []

Field Definitions

Examples

Example 1: Feature Decomposition

Input:

problem: "Implement user authentication system"
strategy: "by user story"

The work is scoped to the web application only, on a 4-week timeline.

Output:

decomposition:
  goal: "Implement user authentication system"
  depth: 2
  total_subproblems: 8
  granularity: story
subproblems:
  - id: "SG-1"
    name: "User Registration"
    description: "Allow new users to create accounts"
    parent: null
    level: 1
    dependencies: []
    acceptance_criteria:
      - criterion: "User can register with email and password"
        testable: true
        priority: required
      - criterion: "Email verification sent on registration"
        testable: true
        priority: required
      - criterion: "Duplicate email rejected with clear message"
        testable: true
        priority: required
    estimated_effort: "3d"
    parallelizable: true
  - id: "SG-2"
    name: "User Login"
    description: "Allow existing users to authenticate"
    parent: null
    level: 1
    dependencies: ["SG-1"]
    acceptance_criteria:
      - criterion: "User can login with email and password"
        testable: true
        priority: required
      - criterion: "Failed login shows error without revealing which field wrong"
        testable: true
        priority: required
      - criterion: "Session created on successful login"
        testable: true
        priority: required
    estimated_effort: "2d"
    parallelizable: false
  - id: "SG-3"
    name: "Password Reset"
    description: "Allow users to recover account access"
    parent: null
    level: 1
    dependencies: ["SG-1"]
    acceptance_criteria:
      - criterion: "User can request password reset via email"
        testable: true
        priority: required
      - criterion: "Reset link expires after 24 hours"
        testable: true
        priority: required
      - criterion: "New password must meet complexity requirements"
        testable: true
        priority: required
    estimated_effort: "2d"
    parallelizable: true
  - id: "SG-4"
    name: "Session Management"
    description: "Manage user sessions securely"
    parent: null
    level: 1
    dependencies: ["SG-2"]
    acceptance_criteria:
      - criterion: "Sessions expire after 24 hours of inactivity"
        testable: true
        priority: required
      - criterion: "User can logout, invalidating session"
        testable: true
        priority: required
      - criterion: "Multiple sessions per user supported"
        testable: true
        priority: optional
    estimated_effort: "2d"
    parallelizable: false
  - id: "SG-5"
    name: "OAuth2 Integration"
    description: "Allow login via Google/GitHub"
    parent: null
    level: 1
    dependencies: ["SG-2"]
    acceptance_criteria:
      - criterion: "User can login via Google OAuth"
        testable: true
        priority: required
      - criterion: "User can login via GitHub OAuth"
        testable: true
        priority: required
      - criterion: "OAuth user linked to existing account if email matches"
        testable: true
        priority: required
    estimated_effort: "3d"
    parallelizable: true
  - id: "SG-6"
    name: "Rate Limiting"
    description: "Prevent brute force attacks"
    parent: null
    level: 1
    dependencies: ["SG-2"]
    acceptance_criteria:
      - criterion: "Max 5 failed login attempts per 15 minutes per IP"
        testable: true
        priority: required
      - criterion: "CAPTCHA shown after 3 failed attempts"
        testable: true
        priority: required
    estimated_effort: "1d"
    parallelizable: true
  - id: "SG-7"
    name: "Security Audit Logging"
    description: "Log all auth events for audit"
    parent: null
    level: 1
    dependencies: ["SG-2"]
    acceptance_criteria:
      - criterion: "All login attempts logged with timestamp and IP"
        testable: true
        priority: required
      - criterion: "Password changes logged"
        testable: true
        priority: required
      - criterion: "Logs retained for 90 days"
        testable: true
        priority: required
    estimated_effort: "1d"
    parallelizable: true
  - id: "SG-8"
    name: "Two-Factor Authentication"
    description: "Add optional 2FA for users"
    parent: null
    level: 1
    dependencies: ["SG-2", "SG-4"]
    acceptance_criteria:
      - criterion: "User can enable TOTP-based 2FA"
        testable: true
        priority: required
      - criterion: "Recovery codes provided on 2FA setup"
        testable: true
        priority: required
      - criterion: "2FA prompt on login when enabled"
        testable: true
        priority: required
    estimated_effort: "3d"
    parallelizable: false
structure:
  goal: "Implement user authentication system"
  children:
    - id: "SG-1"
      name: "User Registration"
      children: []
    - id: "SG-2"
      name: "User Login"
      children: []
    - id: "SG-3"
      name: "Password Reset"
      children: []
    - id: "SG-4"
      name: "Session Management"
      children: []
    - id: "SG-5"
      name: "OAuth2 Integration"
      children: []
    - id: "SG-6"
      name: "Rate Limiting"
      children: []
    - id: "SG-7"
      name: "Security Audit Logging"
      children: []
    - id: "SG-8"
      name: "Two-Factor Authentication"
      children: []
dependencies:
  - from: "SG-1"
    to: "SG-2"
  - from: "SG-1"
    to: "SG-3"
  - from: "SG-2"
    to: "SG-4"
  - from: "SG-2"
    to: "SG-5"
  - from: "SG-2"
    to: "SG-6"
  - from: "SG-2"
    to: "SG-7"
  - from: "SG-2"
    to: "SG-8"
  - from: "SG-4"
    to: "SG-8"
constraints:
  - type: scope
    description: "Web application only, no mobile"
    affects: ["SG-1", "SG-2", "SG-5"]
  - type: time
    description: "4 week timeline"
    affects: ["SG-8"]
gaps: []
overlaps: []
confidence: 0.9
evidence_anchors:
  - "requirement:auth-system"
assumptions:
  - "Email service available for verification"
  - "OAuth provider apps already created"
  - "No existing user database to migrate"

Evidence pattern: Each subproblem has testable acceptance criteria, dependencies mapped.

Verification

• All aspects of goal covered
• No gaps in coverage
• No significant overlaps
• Acceptance criteria testable
• Dependencies form valid DAG

Verification tools: Read (for requirement analysis)

Safety Constraints

• mutation: false
• requires_checkpoint: false
• requires_approval: false
• risk: low

Capability-specific rules:

• Always verify completeness
• Flag gaps explicitly
• Resolve overlaps
• Ensure acceptance criteria are testable
• Note assumptions that affect decomposition

Composition Patterns

Commonly follows:

• retrieve - Gather requirements
• inspect - Understand existing system
• explain - Clarify goal before decomposing

Commonly precedes:

• plan - Plan decomposed subproblems (REQUIRED by plan)
• prioritize - Order subproblems
• schedule - Time-order subproblems
• delegate - Assign subproblems

Anti-patterns:

• Never decompose without understanding goal
• Never leave gaps unidentified
• Never skip acceptance criteria

Workflow references:

• See reference/composition_patterns.md for plan requiring decompose