Task Decomposition

---
name: task-decomposition
domain: dev
description: |
  [METHODOLOGY] Tech-spec decomposition into atomic task files with
  parallel creation and validation. Preloaded by dev-tech-architect agent.
---

# Task Decomposition

Decompose tech-spec Implementation Tasks into individual task files with parallel creation and validation.

**Input:** `work/{feature}/tech-spec.md` (status: approved)
**Output:** `work/{feature}/tasks/*.md` (validated)
**Language:** Task files in English, communication in Russian

## Integrity rules (read before Phase 1)

Decomposition is a lossy migration of intent, not a summary. The rules that keep meaning intact
across the conversion live in one shared file:
[decomposition-integrity.md](references/decomposition-integrity.md).

Load it before creating tasks. Non-negotiable subset: every task names its **Source** and repeats
the **Common objective**; the source wins on any conflict with task wording; requirements that
exist because of a risk carry that risk into `## Non-goals / must not break`; small same-shape
edits batch into ONE task instead of one seat each; the coverage check in §6 runs before the set
is handed over.

## Phase 1: Create Tasks

1. Ask user for feature name if not provided.

2. Read `work/{feature}/tech-spec.md`. Check frontmatter `status: approved`.
   If not approved — tell user: "tech-spec не утверждён. Сначала запусти `/new-tech-spec` и доведи до approved." Stop.

3. Read `work/{feature}/user-spec.md`.

4. Note the task template path: `~/.claude/shared/work-templates/tasks/task.md.template`

5. Read skills/reviewers catalog from [skills-and-reviewers.md](~/.claude/skills/tech-spec-planning/references/skills-and-reviewers.md) — for passing correct skills/reviewers to task-creators.

6. For each task in Implementation Tasks — launch [`task-creator`](~/.claude/agents/task-creator.md) subagent in parallel.
   Pass each task-creator:
   - feature_path, task_number, task_name
   - template_path: `~/.claude/shared/work-templates/tasks/task.md.template`
   - files_to_modify, files_to_read (from tech-spec)
   - depends_on, wave, skills, reviewers, verify (from tech-spec)
   - teammate_name (if specified in tech-spec, optional)
   Each task-creator copies the template to `tasks/{N}.md` first, then edits each section in place. This ensures no sections are skipped.

7. Confirm each task-creator returned a file path. Skip reading task content — preserve context budget for validation phase.
8. Git commit: `draft(tasks): create {N} tasks from tech-spec for {feature}`

**Checkpoint:**
- [ ] All `tasks/*.md` files created
- [ ] Each task-creator returned file path
- [ ] Draft committed

## Phase 2: Validation (up to 3 iterations)

Tech-spec was already validated by 6 validators. This phase checks only: (1) task-creator correctly expanded tasks by template, (2) no mismatches with real code appeared during detailing.

### Validators

Launch both in parallel:

[`task-validator`](~/.claude/agents/task-validator.md) (sonnet) — Template Compliance + AC/TDD carry-forward:
- Batch: 5 tasks per call
- Pass: feature_path, task_numbers array, batch_number, iteration
- Report: `logs/tasks/template-batch{N}-review.json`

[`reality-checker`](~/.claude/agents/reality-checker.md) (sonnet) — Reality & Adequacy:
- Batch: 3 tasks per call
- Pass: feature_path, task_numbers array, batch_number, iteration
- Report: `logs/tasks/reality-batch{N}-review.json`

### Process

1. Launch both validators in parallel (task-validator in batches of 5, reality-checker in batches of 3).
2. Read JSON reports, collect findings.
3. If issues found — for each task with issues, launch [`task-creator`](~/.claude/agents/task-creator.md) in fix mode:
   - Pass: same inputs as creation + `mode: fix` + `findings` from validators
   - task-creator reads existing task, applies fixes, overwrites file
4. After each validation round, git commit: `chore(tasks): validation round {N} — {summary}`
5. Re-validate fixed tasks (repeat 1-4). Maximum 3 iterations.
6. If problems remain after 3rd iteration — show user: "Вот что осталось — давай решим вместе."

### Cross-Task Integration Check

After individual validation passes, run a final cross-task check:

1. Launch both validators on ALL tasks in a single batch (not split into smaller batches):
   - `task-validator` — focus: shared resource ownership (one owner, consumers depend_on owner), no competing instances in same wave
   - `reality-checker` — focus: duplicate heavy resource init, hidden dependencies, inconsistent approaches across tasks

2. If issues found → launch `task-creator` in fix mode for affected tasks. Re-validate fixed tasks.

3. Max 2 iterations for cross-task check (on top of the 3 individual iterations).

**Checkpoint:**
- [ ] Both validators: status=approved OR user resolved remaining issues
- [ ] Cross-task integration check: no cross-task conflicts

## Phase 3: Present to User

1. Summary: task count, waves, dependencies, validation results (iterations, issues found/fixed).
2. Wait for user approval.
3. Git commit: `chore(tasks): task decomposition approved for {feature}`
4. Suggest next step: the engagement-workflow deliver phase runs the tasks wave-based.

**Checkpoint:**
- [ ] Summary presented to user
- [ ] User approved task decomposition
- [ ] Approval committed

## Per-task contract (S2 — when A.contracts is enabled)

On M/L engagements run with `A.contracts` on, each `tasks/{id}.md` ALSO carries a `## Contract (co-signed)` section (the per-task acceptance rubric). You do NOT author it — leave it for the engine's contract handshake (owner proposes assertions in-band → reviewer co-signs and writes the section). Schema: `engagement-protocol` §"`tasks/{id}.md` → `## Contract (co-signed)`". It binds the per-task review only and never waives `criteria.md`.

## Final Check

- [ ] All phases completed (tasks created, validation passed)
- [ ] All tasks match template (frontmatter: status, depends_on, wave, skills, reviewers, teammate_name)
- [ ] Validation: both validators passed or user confirmed remaining issues