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

Parameter	Required	Type	Description
goal	Yes	string or object	The goal to decompose
depth	No	integer	Maximum decomposition depth (default: 3)
constraints	No	object	Boundaries, limitations, scope
granularity	No	string	Target size: epic, story, task (default: story)
context	No	object	Background information

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

Field	Type	Description
decomposition	object	Summary of decomposition
subgoals	array	Flat list of all subgoals
hierarchy	array	Tree structure of subgoals
constraints	array	Boundaries affecting subgoals
gaps	array	Missing coverage identified
overlaps	array	Redundant coverage identified
confidence	number	0.0-1.0 based on completeness

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