admin/.cursor/skills/decompose/SKILL.md

---
name: decompose
description: |
  Decompose planned components into atomic implementable tasks with bootstrap structure plan.
  4-step workflow: bootstrap structure plan, component task decomposition, blackbox test task decomposition, and cross-task verification.
  Supports full decomposition (_docs/ structure), single component mode, and tests-only mode.
  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 8 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

Determine the operating mode based on invocation before any other logic runs.

**Default** (no explicit input file provided):

- 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

**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 detected mode and resolved paths to the user before proceeding.

### Step Applicability by Mode

| Step | File | Default | 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` | ✓ | — | — |
| 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

**Default:**

| 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 skill |
| `DOCUMENT_DIR/system-flows.md` | System flows from plan skill |
| `DOCUMENT_DIR/components/[##]_[name]/description.md` | Component specs from plan skill |
| `DOCUMENT_DIR/tests/` | Blackbox test specs from plan skill |

**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)

**Default:**

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`.

### 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 detected mode (see Step Applicability table). Update status as each step/component completes.

## Workflow

### Step 1: Bootstrap Structure Plan (default 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 (default mode only)

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

---

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

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

---

### Step 3: Blackbox Test Task Decomposition (default and tests-only modes)

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

---

### Step 4: Cross-Task Verification (default 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 8 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 8 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: Resolve mode (default / single component / tests-only) │
│                                                                 │
│ DEFAULT MODE:                                                   │
│  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]                          │
│  2.   Component Tasks     → steps/02_task-decomposition.md      │
│  3.   Blackbox Tests      → steps/03_blackbox-test-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│
└────────────────────────────────────────────────────────────────┘
```