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

name, description, category, tags, disable-model-invocation

name	description	category	tags	disable-model-invocation
decompose	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"	build	decomposition tasks dependencies work-items implementation-prep	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	✓	—	—
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 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]                          │
│  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│
└────────────────────────────────────────────────────────────────┘