annotations/.cursor/skills/decompose/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
decompose	Decompose planned components into atomic implementable features with bootstrap structure plan. 4-step workflow: bootstrap structure plan, feature decomposition, cross-component verification, and Jira task creation. Supports project mode (_docs/ structure), single component mode, and standalone mode (@file.md). Trigger phrases: - "decompose", "decompose features", "feature decomposition" - "task decomposition", "break down components" - "prepare for implementation"	true

Feature Decomposition

Decompose planned components into atomic, implementable feature specs with a bootstrap structure plan through a systematic workflow.

Core Principles

• Atomic features: each feature 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
• Save immediately: write artifacts to disk after each component; never accumulate unsaved work
• Ask, don't assume: when requirements are ambiguous, ask the user before proceeding
• Plan, don't code: this workflow produces documents and Jira tasks, never implementation code

Context Resolution

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

Full project mode (no explicit input file provided):

• PLANS_DIR: _docs/02_plans/
• TASKS_DIR: _docs/02_tasks/
• Reads from: _docs/00_problem/, _docs/01_solution/, PLANS_DIR
• Runs Step 1 (bootstrap) + Step 2 (all components) + Step 3 (cross-verification) + Step 4 (Jira)

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

• PLANS_DIR: _docs/02_plans/
• TASKS_DIR: _docs/02_tasks/
• Derive <topic>, component number, and component name from the file path
• Ask user for the parent Epic ID
• Runs Step 2 (that component only) + Step 4 (Jira)
• Overwrites existing feature files in that component's TASKS_DIR subdirectory

Standalone mode (explicit input file provided, not within _docs/02_plans/):

• INPUT_FILE: the provided file (treated as a component spec)
• Derive <topic> from the input filename (without extension)
• TASKS_DIR: _standalone/<topic>/tasks/
• Guardrails relaxed: only INPUT_FILE must exist and be non-empty
• Ask user for the parent Epic ID
• Runs Step 2 (that component only) + Step 4 (Jira)

Announce the detected mode and resolved paths to the user before proceeding.

Input Specification

Required Files

Full project mode:

File	Purpose
_docs/00_problem/problem.md	Problem description and context
_docs/00_problem/restrictions.md	Constraints and limitations (if available)
_docs/00_problem/acceptance_criteria.md	Measurable acceptance criteria (if available)
_docs/01_solution/solution.md	Finalized solution
PLANS_DIR/<topic>/architecture.md	Architecture from plan skill
PLANS_DIR/<topic>/system-flows.md	System flows from plan skill
PLANS_DIR/<topic>/components/[##]_[name]/description.md	Component 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

Standalone mode:

File	Purpose
INPUT_FILE (the provided file)	Component spec to decompose

Prerequisite Checks (BLOCKING)

Full project mode:

1. At least one <topic>/ directory exists under PLANS_DIR with architecture.md and components/ — STOP if missing
2. If multiple topics exist, ask user which one to decompose
3. Create TASKS_DIR if it does not exist
4. If TASKS_DIR/<topic>/ already exists, 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
2. Create the component's subdirectory under TASKS_DIR if it does not exist

Standalone mode:

1. INPUT_FILE exists and is non-empty — STOP if missing
2. Create TASKS_DIR if it does not exist

Artifact Management

Directory Structure

TASKS_DIR/<topic>/
├── initial_structure.md                        (Step 1, full mode only)
├── cross_dependencies.md                       (Step 3, full mode only)
├── SUMMARY.md                                  (final)
├── [##]_[component_name]/
│   ├── [##].[##]_feature_[feature_name].md
│   ├── [##].[##]_feature_[feature_name].md
│   └── ...
├── [##]_[component_name]/
│   └── ...
└── ...

Save Timing

Step	Save immediately after	Filename
Step 1	Bootstrap structure plan complete	initial_structure.md
Step 2	Each component decomposed	[##]_[name]/[##].[##]_feature_[feature_name].md
Step 3	Cross-component verification complete	cross_dependencies.md
Step 4	Jira tasks created	Jira via MCP
Final	All steps complete	SUMMARY.md

Resumability

If TASKS_DIR/<topic>/ already contains artifacts:

1. List existing files and match them to the save timing table
2. Identify the last completed component based on which feature files exist
3. Resume from the next incomplete component
4. Inform the user which components are being skipped

Progress Tracking

At the start of execution, create a TodoWrite with all applicable steps. Update status as each step/component completes.

Workflow

Step 1: Bootstrap Structure Plan (full project mode only)

Role: Professional software architect Goal: Produce initial_structure.md describing the project skeleton for implementation Constraints: This is a plan document, not code. The implement-initial command executes it.

1. Read architecture.md, all component specs, and system-flows.md from PLANS_DIR
2. Read problem, solution, and restrictions from _docs/00_problem/ and _docs/01_solution/
3. Research best implementation patterns for the identified tech stack
4. Document the structure plan using templates/initial-structure.md

Self-verification:

• All components have corresponding folders in the layout
• All inter-component interfaces have DTOs defined
• CI/CD stages cover build, lint, test, security, deploy
• Environment strategy covers dev, staging, production
• Test structure includes unit and integration test locations

Save action: Write initial_structure.md

BLOCKING: Present structure plan summary to user. Do NOT proceed until user confirms.

---

Step 2: Feature Decomposition (all modes)

Role: Professional software architect Goal: Decompose each component into atomic, implementable feature specs Constraints: Behavioral specs only — describe what, not how. No implementation code.

For each component (or the single provided component):

1. Read the component's description.md and tests.md (if available)
2. Decompose into atomic features; create only 1 feature if the component is simple or atomic
3. Split into multiple features only when it is necessary and would be easier to implement
4. Do not create features of other components — only features of the current component
5. Each feature should be atomic, containing 0 APIs or a list of semantically connected APIs
6. Write each feature spec using templates/feature-spec.md
7. Estimate complexity per feature (1, 2, 3, 5 points); no feature should exceed 5 points — split if it does
8. Note feature dependencies (within component and cross-component)

Self-verification (per component):

• Every feature is atomic (single concern)
• No feature exceeds 5 complexity points
• Feature dependencies are noted
• Features cover all interfaces defined in the component spec
• No features duplicate work from other components

Save action: Write each [##]_[name]/[##].[##]_feature_[feature_name].md

---

Step 3: Cross-Component Verification (full project mode only)

Role: Professional software architect and analyst Goal: Verify feature consistency across all components Constraints: Review step — fix gaps found, do not add new features

1. Verify feature dependencies across all components are consistent
2. Check no gaps: every interface in architecture.md has features covering it
3. Check no overlaps: features don't duplicate work across components
4. Produce dependency matrix showing cross-component feature dependencies
5. Determine recommended implementation order based on dependencies

Self-verification:

• Every architecture interface is covered by at least one feature
• No circular feature dependencies across components
• Cross-component dependencies are explicitly noted in affected feature specs

Save action: Write cross_dependencies.md

BLOCKING: Present cross-component summary to user. Do NOT proceed until user confirms.

---

Step 4: Jira Tasks (all modes)

Role: Professional product manager Goal: Create Jira tasks from feature specs under the appropriate parent epics Constraints: Be concise — fewer words with the same meaning is better

1. For each feature spec, create a Jira task following the parsing rules and field mapping from gen_jira_task_and_branch.md (skip branch creation and file renaming — those happen during implementation)
2. In full mode: search Jira for epics matching component names/labels to find parent epic IDs
3. In single component mode: use the Epic ID obtained during context resolution
4. In standalone mode: use the Epic ID obtained during context resolution
5. Do NOT create git branches or rename files — that happens during implementation

Self-verification:

• Every feature has a corresponding Jira task
• Every task is linked to the correct parent epic
• Task descriptions match feature spec content

Save action: Jira tasks created via MCP

---

Summary Report

After all steps complete, write SUMMARY.md using templates/summary.md as structure.

Common Mistakes

• Coding during decomposition: this workflow produces specs, never code
• Over-splitting: don't create many features if the component is simple — 1 feature is fine
• Features exceeding 5 points: split them; no feature should be too complex for a single task
• Cross-component features: each feature 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

Escalation Rules

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

Methodology Quick Reference

┌────────────────────────────────────────────────────────────────┐
│            Feature Decomposition (4-Step Method)               │
├────────────────────────────────────────────────────────────────┤
│ CONTEXT: Resolve mode (full / single component / standalone)   │
│ 1. Bootstrap Structure  → initial_structure.md (full only)     │
│    [BLOCKING: user confirms structure]                         │
│ 2. Feature Decompose    → [##]_[name]/[##].[##]_feature_*     │
│ 3. Cross-Verification   → cross_dependencies.md (full only)   │
│    [BLOCKING: user confirms dependencies]                      │
│ 4. Jira Tasks           → Jira via MCP                        │
│    ─────────────────────────────────────────────────           │
│    Summary → SUMMARY.md                                        │
├────────────────────────────────────────────────────────────────┤
│ Principles: Atomic features · Behavioral specs · Save now      │
│             Ask don't assume · Plan don't code                 │
└────────────────────────────────────────────────────────────────┘