Decompose

Intent

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

Success criteria:

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

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Procedure

1. Understand the goal: Clarify what needs to be achieved

   • Parse the goal 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 subgoals: Define each component

   • Clear, specific objective
   • Bounded scope
   • Measurable outcome
   • Independent when possible

4. Define dependencies: Map relationships

   • Which subgoals block others?
   • Which can proceed in parallel?
   • Are there shared resources?
   • Create dependency graph

5. Add acceptance criteria: Specify done conditions

   • Testable conditions
   • Measurable outcomes
   • Quality requirements
   • Edge case handling

6. Validate completeness: Check coverage

   • Do subgoals cover entire goal?
   • Any gaps or overlaps?
   • Are boundaries clear?
   • Is granularity consistent?

7. Recurse if needed: Decompose large subgoals

   • Check against target granularity
   • Decompose subgoals 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_subgoals: integer
  granularity: epic | story | task
subgoals:
  - id: string
    name: string
    description: string
    parent: string | null  # Parent subgoal ID
    level: integer  # Depth in tree
    dependencies: array[string]
    acceptance_criteria:
      - criterion: string
        testable: boolean
        priority: required | optional
    estimated_effort: string | null
    parallelizable: boolean
hierarchy:
  - id: string
    name: string
    children: array  # Nested subgoals
constraints:
  - type: scope | time | resource | technical
    description: string
    affects: array[string]  # Subgoal IDs
gaps:
  - description: string
    suggestion: string
overlaps:
  - subgoals: array[string]
    description: string
    resolution: string
confidence: 0..1
evidence_anchors: ["source:ref"]
assumptions: []

Field Definitions

Examples

Example 1: Feature Decomposition

Input:

goal: "Implement user authentication system"
granularity: story
constraints:
  scope: "Web application only"
  timeline: "4 weeks"

Output:

decomposition:
  goal: "Implement user authentication system"
  depth: 2
  total_subgoals: 8
  granularity: story
subgoals:
  - 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
hierarchy:
  - 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: []
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 subgoal 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 subgoals (REQUIRED by plan)
• prioritize - Order subgoals
• schedule - Time-order subgoals
• delegate - Assign subgoals

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