autopilot/.cursor/skills/decompose/steps/02_task-decomposition.md

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

Role: Professional software architect Goal: Decompose each component into atomic, implementable task specs — numbered sequentially starting from 02. Constraints: Behavioral specs only — describe what, not how. No implementation code.

Numbering

Tasks are numbered sequentially across all components in dependency order. Start from 02 (01 is initial_structure). In single component mode, start from the next available number in TASKS_DIR.

Component ordering

Process components in dependency order — foundational components first (shared models, database), then components that depend on them.

Consult LESSONS.md once at the start of Step 2

If _docs/LESSONS.md exists, read it and note estimation, architecture, or dependencies lessons that may bias task sizing in this pass (e.g., "auth-related changes historically take 2x estimate" → bump any auth task up one complexity tier). Apply the bias when filling the Complexity field in step 7 below. Record which lessons informed estimation in a comment in _dependencies_table.md (Step 4).

Steps

For each component (or the single provided component):

1. Read the component's description.md and tests.md (if available)

2. Decompose into atomic tasks; create only 1 task if the component is simple or atomic

3. Split into multiple tasks only when it is necessary and would be easier to implement

4. Do not create tasks for other components — only tasks for the current component

5. Each task should be atomic, containing 1 API or a list of semantically connected APIs

6. Write each task spec using templates/task.md

7. Estimate complexity per task (1, 2, 3, 5, 8 points); no task should exceed 8 points — split if it does

8. Note task dependencies (referencing tracker IDs of already-created dependency tasks, e.g., AZ-42_initial_structure)

9. Cross-cutting rule: if a concern spans ≥2 components (logging, config loading, auth/authZ, error envelope, telemetry, feature flags, i18n), create ONE shared task under the cross-cutting epic. Per-component tasks declare it as a dependency and consume it; they MUST NOT re-implement it locally. Duplicate local implementations are an Architecture finding (High) in code-review Phase 7 and a Maintainability finding in Phase 6.

10. Shared-models / shared-API rule: classify the task as shared if ANY of the following is true:

    • The component is listed under shared/* in module-layout.md.
    • The task's Scope.Included mentions "public interface", "DTO", "schema", "event", "contract", "API endpoint", or "shared model".
    • The task is parented to a cross-cutting epic.
    • The task is depended on by ≥2 other tasks across different components.

    For every shared task:

    • Produce a contract file at _docs/02_document/contracts/<component>/<name>.md using templates/api-contract.md. Fill Shape, Invariants, Non-Goals, Versioning Rules, and at least 3 Test Cases.
    • Add a mandatory ## Contract section to the task spec pointing at the contract file.
    • For every consuming task, add the contract path to its ## Dependencies section as a document dependency (separate from task dependencies).

    Consumers read the contract file, not the producer's task spec. This prevents interface drift when the producer's implementation detail leaks into consumers.

11. Immediately after writing each task file: create a work item ticket, link it to the component's epic, write the work item ticket ID and Epic ID back into the task header, then rename the file from todo/[##]_[short_name].md to todo/[TRACKER-ID]_[short_name].md.

Self-verification (per component)

• Every task is atomic (single concern)
• No task exceeds 8 complexity points
• Task dependencies reference correct tracker IDs
• Tasks cover all interfaces defined in the component spec
• No tasks duplicate work from other components
• Every task has a work item ticket linked to the correct epic
• Every shared-models / shared-API task has a contract file at _docs/02_document/contracts/<component>/<name>.md and a ## Contract section linking to it
• Every cross-cutting concern appears exactly once as a shared task, not N per-component copies

Save action

Write each todo/[##]_[short_name].md (temporary numeric name), create work item ticket inline, then rename to todo/[TRACKER-ID]_[short_name].md. Update the Task field inside the file to match the new filename. Update Dependencies references in the file to use tracker IDs of the dependency tasks.