decomposing-tasks

What this skill does

# Task Decomposition

Create an execution-ready plan from a feature specification with automatic phase grouping based on file dependencies.

**When to use:** After completing a feature spec with `/spectacular:spec`, to create an implementation plan.

**Announce:** "I'm using the Task Decomposition skill to create an execution plan."

## Input

User will provide: `/spectacular:plan {spec-path}`

Example: `/spectacular:plan @specs/a1b2c3-magic-link-auth/spec.md`

Where `a1b2c3` is the runId and `magic-link-auth` is the feature slug.

## Multi-Repo Support

### Detecting Multi-Repo Mode

Check if workspace contains multiple repos:

```bash
# Detect workspace mode (same as writing-specs skill)
REPO_COUNT=$(find . -maxdepth 2 -name ".git" -type d 2>/dev/null | wc -l | tr -d ' ')
if [ "$REPO_COUNT" -gt 1 ]; then
  echo "Multi-repo workspace detected ($REPO_COUNT repos)"
  WORKSPACE_MODE="multi-repo"
  # List detected repos
  REPOS=$(find . -maxdepth 2 -name ".git" -type d | xargs -I{} dirname {} | sed 's|^\./||' | tr '\n' ' ')
  echo "Available repos: $REPOS"
else
  echo "Single-repo mode"
  WORKSPACE_MODE="single-repo"
fi
```

### Multi-Repo Task Format

In multi-repo mode, each task MUST specify which repo it belongs to:

```markdown
### Task 1.1: Add user_preferences table

**Repo**: backend
**Files**:
- prisma/schema.prisma
- prisma/migrations/*

**Constitution**: @backend/docs/constitutions/current/
```

### Single-Repo Task Format (unchanged)

```markdown
### Task 1.1: Add user_preferences table

**Files**:
- prisma/schema.prisma
- prisma/migrations/*

**Constitution**: @docs/constitutions/current/
```

## Full Workflow

### Step 0: Extract Run ID and Feature Slug from Spec

**First action**: Read the spec and extract the RUN_ID from frontmatter and determine the spec directory.

```bash
# Extract runId from spec frontmatter
RUN_ID=$(grep "^runId:" {spec-path} | awk '{print $2}')
echo "RUN_ID: $RUN_ID"

# Extract feature slug from the spec path
# Path pattern: .../specs/{runId}-{feature-slug}/spec.md
# Use sed to extract directory name without nested command substitution
SPEC_PATH="{spec-path}"
DIR_NAME=$(echo "$SPEC_PATH" | sed 's|^.*specs/||; s|/spec.md$||')
FEATURE_SLUG=$(echo "$DIR_NAME" | sed "s/^${RUN_ID}-//")
echo "FEATURE_SLUG: $FEATURE_SLUG"
```

**CRITICAL**: Execute this entire block as a single multi-line Bash tool call. The comment on the first line is REQUIRED - without it, command substitution `$(...)` causes parse errors.

**If RUN_ID not found:**
Generate one now (for backwards compatibility with old specs):

```bash
# Generate timestamp-based hash for unique ID
TIMESTAMP=$(date +%s)
RUN_ID=$(echo "{feature-name}-$TIMESTAMP" | shasum -a 256 | head -c 6)
echo "Generated RUN_ID: $RUN_ID (spec missing runId)"
```

**CRITICAL**: Execute this entire block as a single multi-line Bash tool call. The comment on the first line is REQUIRED - without it, command substitution `$(...)` causes parse errors.

**Spec Directory Pattern:**
Specs follow the pattern: `specs/{run-id}-{feature-slug}/spec.md`
Plans are generated at: `specs/{run-id}-{feature-slug}/plan.md`

**Announce:** "Using RUN_ID: {run-id} for {feature-slug} implementation"

### Step 0.5: Switch to Worktree Context

**Second action**: After extracting RUN_ID, switch to the worktree created by `/spectacular:spec`.

```bash
# Get absolute repo root to avoid recursive paths
REPO_ROOT=$(git rev-parse --show-toplevel)

# Check if already in correct worktree (avoid double cd)
CURRENT_DIR=$(pwd)
if [[ "$CURRENT_DIR" == "${REPO_ROOT}/.worktrees/${RUN_ID}-main" ]] || [[ "$CURRENT_DIR" == *"/.worktrees/${RUN_ID}-main" ]]; then
  echo "Already in worktree ${RUN_ID}-main"
else
  # Switch to worktree using absolute path
  cd "${REPO_ROOT}/.worktrees/${RUN_ID}-main"
fi
```

**CRITICAL**: Execute this entire block as a single multi-line Bash tool call. The comment on the first line is REQUIRED - without it, command substitution `$(...)` causes parse errors.

**If worktree doesn't exist:**
Error immediately with clear message:

```markdown
**Worktree Not Found**

The worktree for RUN_ID {run-id} doesn't exist.

Run `/spectacular:spec {feature}` first to create the workspace.

Expected worktree: .worktrees/{run-id}-main/
```

**IMPORTANT**: All subsequent operations happen in the worktree context.

- Spec is read from: `.worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/spec.md`
- Plan will be written to: `.worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/plan.md`
- No fallback to main repo (worktree is required)

### Step 1: Dispatch Subagent for Task Decomposition

**Announce:** "Dispatching subagent to generate execution plan from spec."

**IMPORTANT:** Delegate plan generation to a subagent to avoid context bloat. The subagent will read the spec, analyze tasks, and generate the plan in its isolated context.

Use the Task tool with `general-purpose` subagent type:

```
ROLE: Plan generation subagent for spectacular workflow

TASK: Generate execution plan from feature specification

SPEC_PATH: .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/spec.md
RUN_ID: {run-id}
FEATURE_SLUG: {feature-slug}

IMPLEMENTATION:

**Announce:** "I'm performing task decomposition to create an execution plan."

Follow the Task Decomposition Process below to analyze the spec and generate a plan.

**The process will:**

1. Read the spec from SPEC_PATH above
2. Extract or design tasks (handles specs with OR without Implementation Plan section)
3. Validate task quality (no XL tasks, explicit files, proper chunking)
4. Analyze file dependencies between tasks
5. Group tasks into phases (sequential or parallel)
6. Calculate execution time estimates with parallelization savings
7. Generate plan.md in the spec directory

**Critical validations:**
- XL tasks (>8h) -> Must split before planning
- Missing files -> Must specify exact paths
- Missing acceptance criteria -> Must add 3-5 criteria
- Wildcard patterns -> Must be explicit
- Too many S tasks (>30%) -> Bundle into thematic M/L tasks

**Plan output location:**
.worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/plan.md

**Plan frontmatter must include:**
```yaml
---
runId: {run-id}
feature: {feature-slug}
created: YYYY-MM-DD
status: ready
---
```

**After plan generation:**
Report back to orchestrator with:
- Plan location
- Summary of phases and tasks
- Parallelization time savings
- Any validation issues encountered

If validation fails, report issues clearly so user can fix spec and re-run.
```

**Wait for subagent completion** before proceeding to Step 2.

### Step 2: Review Plan Output

After subagent completes, review the generated plan:

```bash
cat specs/{run-id}-{feature-slug}/plan.md
```

Verify:

- Phase strategies make sense (parallel for independent tasks)
- Dependencies are correct (based on file overlaps)
- No XL tasks (all split into M or smaller)
- Time savings calculation looks reasonable

### Step 2.5: Commit Plan to Worktree

After plan generation and review, commit the plan to the `{run-id}-main` branch in the worktree:

```bash
cd .worktrees/${RUN_ID}-main
git add specs/
git commit -m "plan: add ${FEATURE_SLUG} implementation plan [${RUN_ID}]"
```

This ensures the plan is tracked in the worktree branch and doesn't affect the main repo.

### Step 3: Report to User

**IMPORTANT**: After reporting completion, **STOP HERE**. Do not proceed to execution automatically. The user must review the plan and explicitly run `/spectacular:execute` when ready.

Provide comprehensive summary:

````markdown
**Execution Plan Generated & Committed**

**RUN_ID**: {run-id}
**Feature**: {feature-slug}
**Location**: .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/plan.md
**Branch**: {run-id}-main (committed in worktree)

## Plan Summary

**Phases**: {count}

- Sequential: {count} phases ({tasks} tasks)
- Parallel: {count} phases ({tasks} tasks)

**Tasks**: {total-count}

- L (4-8h): {count}
- M (2-4h): {count}
- S (1-2h): {count}

## Time Estimates