Claude-Code-Workflow/.claude/commands/task/breakdown.md

---
name: breakdown
description: Intelligent task decomposition with context-aware subtask generation
usage: /task:breakdown <task-id>
argument-hint: task-id
examples:
  - /task:breakdown IMPL-1
  - /task:breakdown IMPL-1.1
  - /task:breakdown impl-3
---

# Task Breakdown Command (/task:breakdown)

## Overview
Breaks down complex tasks into executable subtasks with context inheritance and agent assignment.

## Core Principles
**Task System:** @~/.claude/workflows/workflow-architecture.md
**File Cohesion:** Related files must stay in same task
**10-Task Limit:** Total tasks cannot exceed 10 (triggers re-scoping)

## Core Features

⚠️ **CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations.

### Breakdown Process
1. **Session Check**: Verify active session contains parent task
2. **Task Validation**: Ensure parent is `pending` status
3. **10-Task Limit Check**: Verify breakdown won't exceed total limit
4. **Manual Decomposition**: User defines subtasks with validation
5. **File Conflict Detection**: Warn if same files appear in multiple subtasks
6. **Similar Function Warning**: Alert if subtasks have overlapping functionality
7. **Context Distribution**: Inherit parent requirements and scope
8. **Agent Assignment**: Auto-assign agents based on subtask type
9. **TODO_LIST Update**: Regenerate TODO_LIST.md with new structure

### Breakdown Rules
- Only `pending` tasks can be broken down
- **Manual breakdown only**: Automated breakdown disabled to prevent violations
- Parent becomes `container` status (not executable)
- Subtasks use format: IMPL-N.M (max 2 levels)
- Context flows from parent to subtasks
- All relationships tracked in JSON
- **10-task limit enforced**: Breakdown rejected if total would exceed 10 tasks
- **File cohesion preserved**: Same files cannot be split across subtasks

## Usage

### Basic Breakdown
```bash
/task:breakdown impl-1
```

Interactive process:
```
Task: Build authentication module
Current total tasks: 6/10

⚠️  MANUAL BREAKDOWN REQUIRED
Define subtasks manually (remaining capacity: 4 tasks):

1. Enter subtask title: User authentication core
   Focus files: models/User.js, routes/auth.js, middleware/auth.js

2. Enter subtask title: OAuth integration
   Focus files: services/OAuthService.js, routes/oauth.js

⚠️  FILE CONFLICT DETECTED:
   - routes/auth.js appears in multiple subtasks
   - Recommendation: Merge related authentication routes

⚠️  SIMILAR FUNCTIONALITY WARNING:
   - "User authentication" and "OAuth integration" both handle auth
   - Consider combining into single task

Proceed with breakdown? (y/n): y

✅ Task IMPL-1 broken down:
▸ IMPL-1: Build authentication module (container)
  ├── IMPL-1.1: User authentication core → code-developer
  └── IMPL-1.2: OAuth integration → code-developer

Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
```

## Decomposition Logic

### Agent Assignment
- **Design/Planning** → `planning-agent`
- **Implementation** → `code-developer`
- **Testing** → `code-review-test-agent`
- **Review** → `review-agent`

### Context Inheritance
- Subtasks inherit parent requirements
- Scope refined for specific subtask
- Implementation details distributed appropriately

## Safety Controls

### File Conflict Detection
**Validates file cohesion across subtasks:**
- Scans `focus_paths` in all subtasks
- Warns if same file appears in multiple subtasks
- Suggests merging subtasks with overlapping files
- Blocks breakdown if critical conflicts detected

### Similar Functionality Detection
**Prevents functional overlap:**
- Analyzes subtask titles for similar keywords
- Warns about potential functional redundancy
- Suggests consolidation of related functionality
- Examples: "user auth" + "login system" → merge recommendation

### 10-Task Limit Enforcement
**Hard limit compliance:**
- Counts current total tasks in session
- Calculates breakdown impact on total
- Rejects breakdown if would exceed 10 tasks
- Suggests re-scoping if limit reached

### Manual Control Requirements
**User-driven breakdown only:**
- No automatic subtask generation
- User must define each subtask title and scope
- Real-time validation during input
- Confirmation required before execution

## Implementation Details

See @~/.claude/workflows/workflow-architecture.md for:
- Complete task JSON schema
- Implementation field structure
- Context inheritance rules
- Agent assignment logic

## Validation

### Pre-breakdown Checks
1. Active session exists
2. Task found in session
3. Task status is `pending`
4. Not already broken down
5. **10-task limit compliance**: Total tasks + new subtasks ≤ 10
6. **Manual mode enabled**: No automatic breakdown allowed

### Post-breakdown Actions
1. Update parent to `container` status
2. Create subtask JSON files
3. Update parent subtasks list
4. Update session stats
5. **Regenerate TODO_LIST.md** with new hierarchy
6. Validate file paths in focus_paths
7. Update session task count

## Examples

### Basic Breakdown
```bash
/task:breakdown impl-1

▸ impl-1: Build authentication (container)
  ├── impl-1.1: Design schema → planning-agent
  ├── impl-1.2: Implement logic → code-developer
  └── impl-1.3: Write tests → code-review-test-agent
```

## Error Handling

```bash
# Task not found
❌ Task IMPL-5 not found

# Already broken down
⚠️ Task IMPL-1 already has subtasks

# Wrong status
❌ Cannot breakdown completed task IMPL-2

# 10-task limit exceeded
❌ Breakdown would exceed 10-task limit (current: 8, proposed: 4)
   Suggestion: Re-scope project into smaller iterations

# File conflicts detected
⚠️ File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2
   Recommendation: Merge subtasks or redistribute files

# Similar functionality warning
⚠️ Similar functions detected: "user login" and "authentication"
   Consider consolidating related functionality

# Manual breakdown required
❌ Automatic breakdown disabled. Use manual breakdown process.
```

## Related Commands

- `/task:create` - Create new tasks
- `/task:execute` - Execute subtasks
- `/workflow:status` - View task hierarchy
- `/workflow:plan` - Plan within 10-task limit

**System ensures**: Manual breakdown control with file cohesion enforcement, similar functionality detection, and 10-task limit compliance