---
name: decompose
description: |
  Decompose planned components into atomic implementable tasks with bootstrap structure plan.
  Workflow entrypoints: implementation task decomposition, single component decomposition, and tests-only decomposition.
  The invoking flow decides which entrypoint to run; this skill executes that selected sequence.
  Trigger phrases:
  - "decompose", "decompose features", "feature decomposition"
  - "task decomposition", "break down components"
  - "prepare for implementation"
  - "decompose tests", "test decomposition"
category: build
tags: [decomposition, tasks, dependencies, work-items, implementation-prep]
disable-model-invocation: true
---

# Task Decomposition

Decompose planned components into atomic, implementable task specs with a bootstrap structure plan through a systematic workflow. All tasks are named with their work item tracker ID prefix in a flat directory.

## Core Principles

- **Atomic tasks**: each task does one thing; if it exceeds 5 complexity points, split it
- **Behavioral specs, not implementation plans**: describe what the system should do, not how to build it
- **Flat structure**: all tasks are tracker-ID-prefixed files in TASKS_DIR — no component subdirectories
- **Save immediately**: write artifacts to disk after each task; never accumulate unsaved work
- **Tracker inline**: create work item ticket immediately after writing each task file
- **Ask, don't assume**: when requirements are ambiguous, ask the user before proceeding
- **Plan, don't code**: this workflow produces documents and work item tickets, never implementation code

## Context Resolution

Resolve the selected entrypoint from the invocation context before any other logic runs. The caller decides whether this is implementation, single component, or tests-only decomposition; this skill only executes the selected sequence.

**Implementation task decomposition** (default; selected by flows before invoking this skill):

- DOCUMENT_DIR: `_docs/02_document/`
- TASKS_DIR: `_docs/02_tasks/`
- TASKS_TODO: `_docs/02_tasks/todo/`
- Reads from: `_docs/00_problem/`, `_docs/01_solution/`, DOCUMENT_DIR
- Produces only implementation tasks. Blackbox/e2e test task files are produced only when the invoking flow selects tests-only decomposition.

**Single component mode** (provided file is within `_docs/02_document/` and inside a `components/` subdirectory):

- DOCUMENT_DIR: `_docs/02_document/`
- TASKS_DIR: `_docs/02_tasks/`
- TASKS_TODO: `_docs/02_tasks/todo/`
- Derive component number and component name from the file path
- Ask user for the parent Epic ID

**Tests-only mode** (provided file/directory is within `tests/`, or `DOCUMENT_DIR/tests/` exists and input explicitly requests test decomposition):

- DOCUMENT_DIR: `_docs/02_document/`
- TASKS_DIR: `_docs/02_tasks/`
- TASKS_TODO: `_docs/02_tasks/todo/`
- TESTS_DIR: `DOCUMENT_DIR/tests/`
- Reads from: `_docs/00_problem/`, `_docs/01_solution/`, TESTS_DIR

Announce the selected entrypoint and resolved paths to the user before proceeding.

### Step Applicability by Mode

| Step | File | Implementation | Single | Tests-only |
|------|------|:--------------:|:------:|:----------:|
| 1 Bootstrap Structure | `steps/01_bootstrap-structure.md` | ✓ | — | — |
| 1t Test Infrastructure | `steps/01t_test-infrastructure.md` | — | — | ✓ |
| 1.5 Module Layout | `steps/01-5_module-layout.md` | ✓ | — | — |
| 1.7 System-Pipeline Tasks | `steps/01-7_system-pipeline-tasks.md` | ✓ | — | — |
| 2 Task Decomposition | `steps/02_task-decomposition.md` | ✓ | ✓ | — |
| 3 Blackbox Test Tasks | `steps/03_blackbox-test-decomposition.md` | — | — | ✓ |
| 4 Cross-Verification | `steps/04_cross-verification.md` | ✓ | — | ✓ |

## Input Specification

### Required Files

**Implementation task decomposition:**

| File | Purpose |
|------|---------|
| `_docs/00_problem/problem.md` | Problem description and context |
| `_docs/00_problem/restrictions.md` | Constraints and limitations |
| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria |
| `_docs/01_solution/solution.md` | Finalized solution |
| `DOCUMENT_DIR/architecture.md` | Architecture from plan/document skill (must contain a `## Architecture Vision` H2 — confirmed user intent) |
| `DOCUMENT_DIR/glossary.md` | Project terminology (confirmed by user in plan Phase 2a.0 or document Step 4.5). Use it to keep task names, component references, and AC wording consistent with the user's vocabulary |
| `DOCUMENT_DIR/system-flows.md` | System flows from plan skill |
| `DOCUMENT_DIR/components/[##]_[name]/description.md` | Component specs from plan skill |
| `DOCUMENT_DIR/tests/` | Optional product acceptance context from test-spec skill; do not create test task files from it in this entrypoint |

**Single component mode:**

| File | Purpose |
|------|---------|
| The provided component `description.md` | Component spec to decompose |
| Corresponding `tests.md` in the same directory (if available) | Test specs for context |

**Tests-only mode:**

| File | Purpose |
|------|---------|
| `TESTS_DIR/environment.md` | Test environment specification (Docker services, networks, volumes) |
| `TESTS_DIR/test-data.md` | Test data management (seed data, mocks, isolation) |
| `TESTS_DIR/blackbox-tests.md` | Blackbox functional scenarios (positive + negative) |
| `TESTS_DIR/performance-tests.md` | Performance test scenarios |
| `TESTS_DIR/resilience-tests.md` | Resilience test scenarios |
| `TESTS_DIR/security-tests.md` | Security test scenarios |
| `TESTS_DIR/resource-limit-tests.md` | Resource limit test scenarios |
| `TESTS_DIR/traceability-matrix.md` | AC/restriction coverage mapping |
| `_docs/00_problem/problem.md` | Problem context |
| `_docs/00_problem/restrictions.md` | Constraints for test design |
| `_docs/00_problem/acceptance_criteria.md` | Acceptance criteria being verified |

### Prerequisite Checks (BLOCKING)

**Implementation task decomposition:**

1. DOCUMENT_DIR contains `architecture.md` and `components/` — **STOP if missing**
2. Create TASKS_DIR and TASKS_TODO if they do not exist
3. If TASKS_DIR subfolders (`todo/`, `backlog/`, `done/`) already contain task files, ask user: **resume from last checkpoint or start fresh?**

**Single component mode:**

1. The provided component file exists and is non-empty — **STOP if missing**

**Tests-only mode:**

1. `TESTS_DIR/blackbox-tests.md` exists and is non-empty — **STOP if missing**
2. `TESTS_DIR/environment.md` exists — **STOP if missing**
3. Create TASKS_DIR and TASKS_TODO if they do not exist
4. If TASKS_DIR subfolders (`todo/`, `backlog/`, `done/`) already contain task files, ask user: **resume from last checkpoint or start fresh?**

## Artifact Management

### Directory Structure

```
TASKS_DIR/
├── _dependencies_table.md
├── todo/
│   ├── [TRACKER-ID]_initial_structure.md
│   ├── [TRACKER-ID]_[short_name].md
│   └── ...
├── backlog/
└── done/
```

**Naming convention**: Each task file is initially saved in `TASKS_TODO/` with a temporary numeric prefix (`[##]_[short_name].md`). After creating the work item ticket, rename the file to use the work item ticket ID as prefix (`[TRACKER-ID]_[short_name].md`). For example: `todo/01_initial_structure.md` → `todo/AZ-42_initial_structure.md`.

If tracker availability fails, follow `.cursor/rules/tracker.mdc` before continuing. Only when the user explicitly chooses `tracker: local` may the numeric prefix remain; in that mode set `Tracker: pending` and `Epic: pending` in the task header and keep the task eligible for later tracker sync.

### Save Timing

| Step | Save immediately after | Filename |
|------|------------------------|----------|
| Step 1 | Bootstrap structure plan complete + work item ticket created + file renamed | `todo/[TRACKER-ID]_initial_structure.md` |
| Step 1.5 | Module layout written | `_docs/02_document/module-layout.md` |
| Step 1t | Test infrastructure bootstrap complete + work item ticket created + file renamed | `todo/[TRACKER-ID]_test_infrastructure.md` |
| Step 2 | Each component task decomposed + work item ticket created + file renamed | `todo/[TRACKER-ID]_[short_name].md` |
| Step 3 | Each blackbox test task decomposed + work item ticket created + file renamed | `todo/[TRACKER-ID]_[short_name].md` |
| Step 4 | Cross-task verification complete | `_dependencies_table.md` |

### Resumability

If TASKS_DIR subfolders already contain task files:

1. List existing `*_*.md` files across `todo/`, `backlog/`, and `done/` (excluding `_dependencies_table.md`) and count them
2. Resume numbering from the next number (for temporary numeric prefix before tracker rename)
3. Inform the user which tasks already exist and are being skipped

## Progress Tracking

At the start of execution, create a TodoWrite with all applicable steps for the selected entrypoint (see Step Applicability table). Update status as each step/component completes.

## Workflow

### Step 1: Bootstrap Structure Plan (implementation mode only)

Read and follow `steps/01_bootstrap-structure.md`.

---

### Step 1t: Test Infrastructure Bootstrap (tests-only mode only)

Read and follow `steps/01t_test-infrastructure.md`.

---

### Step 1.5: Module Layout (implementation mode only)

Read and follow `steps/01-5_module-layout.md`.

---

### Step 1.7: System-Pipeline Tasks (implementation mode only)

Read and follow `steps/01-7_system-pipeline-tasks.md`.

This step exists because per-component task decomposition (Step 2)
produces one task per component but NEVER produces a task whose
deliverable is "the production code that drives the end-to-end
pipeline by calling each component in order against real inputs".
The architecture document describes the loop; nobody owns it. The
GPS-passthrough incident (May 2026) is the canonical failure this
step prevents.

---

### Step 2: Task Decomposition (implementation and single component modes)

Read and follow `steps/02_task-decomposition.md`.

---

### Step 3: Blackbox Test Task Decomposition (tests-only mode only)

Read and follow `steps/03_blackbox-test-decomposition.md`.

---

### Step 4: Cross-Task Verification (implementation and tests-only modes)

Read and follow `steps/04_cross-verification.md`.

## Common Mistakes

- **Coding during decomposition**: this workflow produces specs, never code
- **Over-splitting**: don't create many tasks if the component is simple — 1 task is fine
- **Tasks exceeding 5 points**: split them; no task should be too complex for a single implementer
- **Cross-component tasks**: each task belongs to exactly one component
- **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation
- **Creating git branches**: branch creation is an implementation concern, not a decomposition one
- **Creating component subdirectories**: all tasks go flat in `TASKS_TODO/`
- **Forgetting tracker**: every task must have a work item ticket created inline — do not defer to a separate step
- **Forgetting to rename**: after work item ticket creation, always rename the file from numeric prefix to tracker ID prefix

## Escalation Rules

| Situation | Action |
|-----------|--------|
| Ambiguous component boundaries | ASK user |
| Task complexity exceeds 5 points after splitting | ASK user |
| Missing component specs in DOCUMENT_DIR | ASK user |
| Cross-component dependency conflict | ASK user |
| Tracker epic not found for a component | ASK user for Epic ID |
| Task naming | PROCEED, confirm at next BLOCKING gate |

## Methodology Quick Reference

```
┌────────────────────────────────────────────────────────────────┐
│          Task Decomposition (Multi-Mode)                        │
├────────────────────────────────────────────────────────────────┤
│ CONTEXT: Invoke the selected entrypoint (implementation / single / tests-only) │
│                                                                 │
│ IMPLEMENTATION TASK DECOMPOSITION:                              │
│  1.   Bootstrap Structure → steps/01_bootstrap-structure.md     │
│       [BLOCKING: user confirms structure]                       │
│  1.5  Module Layout       → steps/01-5_module-layout.md         │
│       [BLOCKING: user confirms layout]                          │
│  1.7  System-Pipeline     → steps/01-7_system-pipeline-tasks.md │
│       [BLOCKING: user confirms pipeline owners]                 │
│  2.   Component Tasks     → steps/02_task-decomposition.md      │
│  4.   Cross-Verification  → steps/04_cross-verification.md      │
│       [BLOCKING: user confirms dependencies]                    │
│                                                                 │
│ TESTS-ONLY MODE:                                                │
│  1t.  Test Infrastructure → steps/01t_test-infrastructure.md    │
│       [BLOCKING: user confirms test scaffold]                   │
│  3.   Blackbox Tests      → steps/03_blackbox-test-decomposition.md │
│  4.   Cross-Verification  → steps/04_cross-verification.md      │
│       [BLOCKING: user confirms dependencies]                    │
│                                                                 │
│ SINGLE COMPONENT MODE:                                          │
│  2.   Component Tasks     → steps/02_task-decomposition.md      │
├────────────────────────────────────────────────────────────────┤
│ Principles: Atomic tasks · Behavioral specs · Flat structure   │
│   Tracker inline · Rename to tracker ID · Save now · Ask don't assume│
└────────────────────────────────────────────────────────────────┘
```
