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

•
Understand the goal: Clarify what needs to be achieved
- •Parse the goal statement
- •Identify success criteria
- •Note implicit requirements
- •Determine scope boundaries
•
Identify major components: Find natural divisions
- •Functional areas
- •Phases or stages
- •User journeys
- •Technical layers
•
Create subgoals: Define each component
- •Clear, specific objective
- •Bounded scope
- •Measurable outcome
- •Independent when possible
•
Define dependencies: Map relationships
- •Which subgoals block others?
- •Which can proceed in parallel?
- •Are there shared resources?
- •Create dependency graph
•
Add acceptance criteria: Specify done conditions
- •Testable conditions
- •Measurable outcomes
- •Quality requirements
- •Edge case handling
•
Validate completeness: Check coverage
- •Do subgoals cover entire goal?
- •Any gaps or overlaps?
- •Are boundaries clear?
- •Is granularity consistent?
•
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:

yaml

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:

yaml

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

Output:

yaml

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