Use when you have a complete feature spec and need to plan implementation - analyzes task dependencies, groups into sequential/parallel phases, validates task quality (no XL tasks, explicit files), and calculates parallelization time savings
Transforms a feature spec into an execution-ready plan by analyzing file dependencies, grouping tasks into parallel/sequential phases, and validating PR-sized chunks (M/L tasks, no XL). Use after spec completion but before implementation begins.
/plugin marketplace add arittr/spectacular/plugin install spectacular@spectacularThis skill inherits all available tools. When active, it can use any tool Claude has access to.
test-scenarios.mdAnalyze a feature specification and decompose it into an execution-ready plan with automatic phase grouping based on file dependencies.
When to use: After completing a feature spec, before implementation.
Announce: "I'm using the Task Decomposition skill to create an execution plan."
This skill transforms a feature specification into a structured implementation plan by:
Tasks should be PR-sized, thematically coherent units - not mechanical file-by-file splits.
Think like a senior engineer:
Task chunking principles:
Thematic Coherence - Task represents a complete "thing"
Natural PR Size - Reviewable in one sitting (4-7h)
Logical Boundaries - Clear separation points
Stackable - Dependencies flow cleanly
Good chunking examples:
✅ GOOD: PR-sized, thematic chunks
- Task 1: Database Foundation (M - 4h)
- Schema changes + migration + dependency install
- One coherent "foundation" PR
- Task 2: Agent System (L - 6h)
- Agent config + tools + schemas + types
- Complete agent subsystem as a unit
- Task 3: Import Service Layer (M - 4h)
- All service methods + business logic
- Clean layer boundary
- Task 4: API Surface (L - 6h)
- Server actions + SSE route
- Complete API interface
- Task 5: Import UI (L - 7h)
- All components + page + integration
- Complete user-facing feature
Total: 5 tasks, 27h
Each task is a reviewable PR that adds value
❌ BAD: Too granular, mechanical splits
- Task 1: Add schema fields (S - 2h)
- Task 2: Create migration (S - 1h)
- Task 3: Install dependency (S - 1h)
- Task 4: Create agent config (M - 3h)
- Task 5: Create fetch tool (S - 1h)
- Task 6: Create schemas (S - 2h)
- Task 7: Create service (M - 4h)
- Task 8: Create actions (M - 3h)
- Task 9: Create SSE route (M - 3h)
- Task 10: Create form component (S - 2h)
- Task 11: Create progress component (S - 2h)
- Task 12: Create preview component (M - 2h)
- Task 13: Add routes (S - 1h)
- Task 14: Integrate components (S - 1h)
Total: 14 tasks, 28h
Too many tiny PRs, no coherent units
Bundling heuristics:
If you're creating S tasks, ask:
Common bundling patterns:
Read the spec file and extract tasks. The spec may provide tasks in two ways:
Option A: Spec has "Implementation Plan" section (structured task breakdown)
Option B: Spec has no "Implementation Plan" (lean spec - requirements only)
For each task (extracted or designed), capture:
Example extraction:
Spec has:
### Task 1: Database Schema
**Complexity**: M (2-4h)
**Files**:
- prisma/schema.prisma
- prisma/migrations/
**Description**: Add VerificationToken model for Auth.js...
**Acceptance**:
- [ ] Model matches Auth.js spec
- [ ] Migration runs cleanly
Extract to:
{
id: "task-1-database-schema",
description: "Add VerificationToken model",
files: ["prisma/schema.prisma", "prisma/migrations/"],
complexity: "M",
estimated_hours: 3,
acceptance_criteria: [...],
steps: [...]
}
For each task, check for quality issues:
CRITICAL (must fix):
src/**/*.ts) → Must use explicit pathsHIGH (strongly recommend):
Chunking validation:
If task is S (1-2h), verify it's truly standalone:
If >50% of tasks are S, that's a red flag:
If CRITICAL issues found:
If only HIGH issues:
Build dependency graph by analyzing file overlaps:
Algorithm:
For each task T1:
For each task T2 (where T2 appears after T1):
shared_files = intersection(T1.files, T2.files)
If shared_files is not empty:
T2.dependencies.add(T1.id)
T2.dependency_reason = "Shares files: {shared_files}"
Example:
Task 1: ["prisma/schema.prisma"]
Task 2: ["src/lib/models/auth.ts"]
Task 3: ["prisma/schema.prisma", "src/types/auth.ts"]
Analysis:
- Task 2: No dependencies (no shared files with Task 1)
- Task 3: Depends on Task 1 (shares prisma/schema.prisma)
Architectural dependencies: Also add dependencies based on layer order:
Group tasks into phases using dependency graph:
Phase grouping algorithm:
1. Start with tasks that have no dependencies (roots)
2. Group all independent roots into Phase 1
3. Remove roots from graph
4. Repeat until all tasks grouped
For each phase:
- If all tasks independent: strategy = "parallel"
- If any dependencies exist: strategy = "sequential"
Example:
Tasks:
- Task 1: [] (no deps)
- Task 2: [] (no deps)
- Task 3: [task-1, task-2]
- Task 4: [task-3]
Grouping:
Phase 1: [Task 1, Task 2] - parallel (independent)
Phase 2: [Task 3] - sequential (waits for Phase 1)
Phase 3: [Task 4] - sequential (waits for Phase 2)
For each phase, calculate:
Example:
Phase 2 (parallel):
- Task A: 3h
- Task B: 2h
- Task C: 4h
Sequential: 3 + 2 + 4 = 9h
Parallel: max(3, 2, 4) = 4h
Savings: 9 - 4 = 5h (56% faster)
Write plan to {spec-directory}/plan.md:
Template:
# Feature: {Feature Name} - Implementation Plan
> **Generated by:** Task Decomposition skill
> **From spec:** {spec-path}
> **Created:** {date}
## Execution Summary
- **Total Tasks**: {count}
- **Total Phases**: {count}
- **Sequential Time**: {hours}h
- **Parallel Time**: {hours}h
- **Time Savings**: {hours}h ({percent}%)
**Parallel Opportunities:**
- Phase {id}: {task-count} tasks ({hours}h saved)
---
## Phase {N}: {Phase Name}
**Strategy**: {sequential|parallel}
**Reason**: {why this strategy}
### Task {ID}: {Name}
**Files**:
- {file-path-1}
- {file-path-2}
**Complexity**: {S|M|L} ({hours}h)
**Dependencies**: {[task-ids] or "None"}
**Description**:
{What to implement and why}
**Implementation Steps**:
1. {step-1}
2. {step-2}
3. {step-3}
**Acceptance Criteria**:
- [ ] {criterion-1}
- [ ] {criterion-2}
- [ ] {criterion-3}
**Mandatory Patterns**:
> **Constitution**: All code must follow @docs/constitutions/current/
See architecture.md for layer boundaries and patterns.md for required patterns.
**TDD**: Follow `test-driven-development` skill (write test first, watch fail, minimal code, watch pass)
**Quality Gates**:
```bash
pnpm biome check --write .
pnpm test {test-files}
```
{Repeat for all tasks in all phases}
### Step 7: Report to User
After generating plan:
```markdown
✅ Task Decomposition Complete
**Plan Location**: specs/{run-id}-{feature-slug}/plan.md
## Breakdown
- Phases: {count}
- Tasks: {count}
- Complexity: {XL}: {n}, {L}: {n}, {M}: {n}, {S}: {n}
## Execution Strategy
- Sequential Phases: {count} ({tasks} tasks)
- Parallel Phases: {count} ({tasks} tasks)
## Time Estimates
- Sequential Execution: {hours}h
- With Parallelization: {hours}h
- **Time Savings: {hours}h ({percent}% faster)**
## Next Steps
Review plan:
```bash
cat specs/{run-id}-{feature-slug}/plan.md
Execute plan:
/spectacular:execute @specs/{run-id}-{feature-slug}/plan.md
## Quality Rules
**Task Sizing (PR-focused):**
- ⚠️ S (1-2h): Rare - only truly standalone work (e.g., config-only changes)
- Most S tasks should bundle into M
- Ask: "Would a senior engineer PR this alone?"
- ✅ M (3-5h): Sweet spot - most tasks should be this size
- Complete subsystem, layer, or feature slice
- Reviewable in one sitting
- Thematically coherent unit
- ✅ L (5-7h): Complex coherent units (use for major subsystems)
- Full UI layer with all components
- Complete API surface (actions + routes)
- Major feature integration
- ❌ XL (>8h): NEVER - always split into M/L tasks
**Chunking Standards:**
- ❌ <30% S tasks is a red flag (too granular)
- ✅ Most tasks should be M (60-80%)
- ✅ Some L tasks for major units (10-30%)
- ✅ Rare S tasks for truly standalone work (<10%)
**File Specificity:**
- ✅ `src/lib/models/auth.ts`
- ✅ `src/components/auth/LoginForm.tsx`
- ❌ `src/**/*.ts` (too vague)
- ❌ `src/lib/models/` (specify exact files)
**Acceptance Criteria:**
- ✅ 3-5 specific, testable criteria
- ✅ Quantifiable (tests pass, build succeeds, API returns 200)
- ❌ Vague ("works well", "is good")
- ❌ Too many (>7 - task is too large)
**Dependencies:**
- ✅ Minimal (only true blockers)
- ✅ Explicit reasons (shares file X)
- ❌ Circular dependencies
- ❌ Over-constrained (everything depends on everything)
## Error Handling
### Spec Has Insufficient Information
If spec has neither "Implementation Plan" nor enough detail to design tasks:
❌ Cannot decompose - spec lacks implementation details
The spec must have either:
Current spec has:
Add more implementation details to the spec, then re-run: /spectacular:plan @specs/{run-id}-{feature-slug}/spec.md
### Critical Quality Issues
If tasks have critical issues:
❌ Task Quality Issues - Cannot Generate Plan
Critical Issues Found:
Fix these issues in the spec, then re-run: /spectacular:plan @specs/{run-id}-{feature-slug}/spec.md
### Circular Dependencies
If dependency graph has cycles:
❌ Circular Dependencies Detected
Task A depends on Task B Task B depends on Task C Task C depends on Task A
This is impossible to execute. Review task organization.
## Integration with Other Skills
**Before:** Use `brainstorming` and `spec-feature` to create complete spec
**After:** Use `/execute` command to run plan with `subagent-driven-development`
**Pairs with:**
- `subagent-driven-development` - Executes individual tasks
- `finishing-a-development-branch` - Completes implementation
## Project-Specific Configuration
For projects with a constitution, reference it in every task:
> **Constitution**: All tasks MUST follow @docs/constitutions/current/
Every task must include:
- Reference to constitution for architecture (layer boundaries, dependencies)
- Reference to constitution for patterns (validation, state management, etc.)
- Quality gates (linting, testing, building)
**Quality gates:**
```bash
pnpm biome check --write .
pnpm test
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.