Design Task Decomposition

---
name: design-task-decomposition
domain: design
description: |
  [METHODOLOGY] Decompose a design engagement plan into atomic
  task files (engagement/tasks/*.md). Each task = one specialist + one
  deliverable + measurable done-when. Enables targeted re-dispatch on iter-2
  REJECT instead of re-running the whole brand/UI phase.

  Pure reference — invoked by design-lead at Phase 2.5 (after plan.md,
  before dispatch). Mandatory for size: L. Recommended for size: M with ≥2
  specialists. Skipped on size: S (single deliverable).
---

# Design task decomposition

Design engagements without atomic task files force the entire brand or UI
phase to restart on REJECT. With atomic tasks, the lead re-dispatches only
the broken unit (one logo direction, one component spec, one screen variant).

## When to decompose

| size | Required? | Rationale |
|---|---|---|
| **S** | NO | Single artefact (one logo refresh, one icon set tweak) — `plan.md` is enough. |
| **M** | RECOMMENDED if ≥2 specialists OR brand+UI mixed | iter-2 cost saving outweighs decomposition overhead. |
| **L** | YES | Full rebrand + product UI + design system requires explicit dependency graph and token-propagation tracking. |

If the plan skips decomposition on a size: L engagement, the handoff gate fails
(handoff-precheck) on missing `tasks/` — same gate as a missing `## Validation log`.

## Inputs

- `engagement/criteria.md` (locked)
- `engagement/plan.md` (lead, Phase 2 output)

## Output

- `engagement/tasks/{NN}-{slug}.md` — one file per atomic task
- `engagement/tasks/INDEX.md` — manifest with wave grouping (mandatory for L)

## Integrity rules (read before drafting tasks)

Domain-neutral rules for keeping intent intact across the conversion:
[decomposition-integrity.md](~/.claude/skills/task-decomposition/references/decomposition-integrity.md).

Non-negotiable subset: every task names its **Source** (the `crit-N` or the `plan.md` section it
comes from) and repeats the **Common objective**; the source wins on any conflict with task
wording; a requirement that exists because of a risk carries that risk into `## Non-goals / must
not break` — in design that is usually the regression the rework must not reintroduce; small
same-shape edits batch into ONE task instead of one specialist seat each; the coverage check in §6
runs before the set goes to the workflow.

## Atomic task = one of these shapes

A design task is "atomic" when its rework wouldn't cascade into adjacent tasks
in the same wave. Design atoms by track:

| Track | Atom shape | Example |
|---|---|---|
| **Brand voice** | one voice axis (formal/playful, terse/expansive) with example copy in 3 contexts | "task-01-voice-axis-formality.md" |
| **Logo** | one direction (mark + wordmark + clearspace), produced as alt 1/2/3 | "task-02-logo-direction-A.md" |
| **CIP / corporate identity** | one surface (business card, letterhead, email signature, social avatar, presentation cover) | "task-04-cip-business-card.md" |
| **Color palette** | one role (primary/secondary/accent/semantic) with full ramp + WCAG contrast pairs | "task-06-palette-primary-ramp.md" |
| **Typography** | one pairing (display + body + mono) with full size scale | "task-07-type-pair-A.md" |
| **Design tokens** | one group (color OR spacing OR radius OR elevation OR motion) | "task-08-tokens-spacing.md" |
| **Component spec** | one component (button, input, card, modal, nav, etc.) — all states + responsive | "task-10-component-button.md" |
| **Screen / page** | one screen variant (theme × breakpoint) | "task-12-screen-dashboard-dark-desktop.md" |
| **UX flow** | one flow (signup, checkout, onboarding step, settings change) | "task-14-flow-signup.md" |
| **Asset pack** | one asset family (icons set, illustrations set, social photos batch) | "task-16-icons-32px-stroke.md" |
| **Presentation slide** | one slide (title, problem, solution, etc.) | "task-18-slide-pricing.md" |

**Anti-atom (don't do this):**
- "task-01-design-the-landing.md" — span; can't re-run partially.
- "task-02-create-design-system.md" — too big; tokens vs components vs screens are different atoms.
- "task-03-make-it-look-good.md" — vibes; not measurable.

If you can't write a measurable acceptance bullet for the task, it's not atomic — split further.

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

On M/L engagements run with `A.contracts` on, each `tasks/{NN}.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`.

## Sequence dependency (CRITICAL for design)

Design has hard sequence rules from `design-lead` skill:

1. Brand (voice, palette, type) → design tokens → components → screens → flows → assets.
2. Token tasks MUST land before component tasks (component depends on token).
3. Component tasks MUST land before screen tasks (screen consumes component).
4. Brand identity tasks (logo, CIP) are independent of token/component chain — separate dependency tree.

Encode this in `depends_on`. The Workflow runs waves in dependency order, so a
screen task with `depends_on: []` is a planning error — tokens must precede it.

## Task file template

```markdown
---
task: {NN}-{slug}                     # NN = 2-digit zero-padded order
engagement: {engagement-name}
domain: design
owner: {specialist-agent-name}        # design-brand-strategist, design-visual-designer, design-ui-designer, design-ux-designer, design-presentation-designer
deliverable_type: {voice-axis | logo-direction | cip-surface | palette-role | type-pairing | token-group | component-spec | screen-variant | ux-flow | asset-pack | slide}
depends_on: [{task-NN}, ...]          # honour brand→tokens→components→screens chain
wave: {N}                             # tasks with same wave can run in parallel
status: pending | in_progress | done | blocked
estimated_effort: XS | S | M          # XS = <30 min, S = ≤2h, M = ≤half day; L per task = split further
validators: [{validator-name}, ...]   # accessibility-validator, ux-review, reality-checker, product-context-validator
crit_refs: [crit-{N}, ...]            # criteria.md bullets this task addresses
theme: light | dark | both            # for screen / component tasks
breakpoint: mobile | tablet | desktop | all  # for screen / component tasks
---

# Task {NN}: {one-line title}

## Goal
One sentence: what observable artefact will exist after this task is done.

## Inputs
- criteria.md crit-N: "{verbatim criterion text}"
- plan.md phase: {phase name}
- prerequisite outputs (if depends_on non-empty): {paths to brand/, design-system/, ui/}

## Steps
1. {action}
2. {action}
3. {action}

Keep ≤ 5 steps. If you need more, the task is too big — split.

## Deliverable
- {artefact path} — e.g. `engagement/design-system/tokens/spacing.json`, `engagement/ui/dashboard-dark-desktop.png`, `engagement/brand/logo/direction-A.svg`

## Done when
- [ ] {testable bullet — e.g. "all 8 spacing values in tokens/spacing.json non-empty"}
- [ ] {validator-specific — e.g. "accessibility-validator passes contrast on each colour pair"}
- [ ] specialist signed off in their executor-report
- [ ] (if ux_heavy) screen captured to `screens/{iter}/{theme}/{surface}.png`
```

## Workflow

### Phase 1: Draft tasks (lead)

1. Read `criteria.md` and `plan.md`.
2. Map each plan.md phase to atom families using the shape table.
3. Apply sequence rules: brand → tokens → components → screens → flows → assets.
4. Assign wave numbers respecting `depends_on`:
   - Wave 1: brand atoms (voice, palette, type) + independent assets (logo direction A/B/C in parallel)
   - Wave 2: design-token atoms (consume palette + type from wave 1)
   - Wave 3: component atoms (consume tokens)
   - Wave 4: screen atoms (consume components)
   - Wave 5: flow atoms (consume screens)
5. Write one `tasks/{NN}-{slug}.md` per atom from the template above.
6. Write `tasks/INDEX.md` with the wave grouping (mandatory for L, recommended for M with ≥6 tasks).

### Phase 2: Validate (lead, single pass)

Design tasks don't need a 3-iteration validation cycle. One self-check pass:

For each task file:
- [ ] `crit_refs` actually cites a `criteria.md` bullet.
- [ ] `owner` is a real agent name (matches `design-*` agent in `~/.claude/agents/`).
- [ ] `depends_on` honours sequence rule (component task depends on a token task; screen depends on component).
- [ ] `## Done when` has at least one bullet measurable WITHOUT the lead's eye ("token JSON has 8 spacing values", "WCAG contrast ≥ 4.5:1 on every text/bg pair", not "feels right").
- [ ] For UI tasks: `theme` field present (light / dark / both).
- [ ] No two tasks deliver to the same path (would overwrite).

If any check fails — fix the file, don't dispatch.

### Phase 3: Execution (the engagement-workflow Workflow runs the waves)

The decomposed `tasks/*.md` feed the Workflow's deliver phase. There is NO mid-lead dispatch tier — each task's `owner` field names the specialist agentType directly, and the Workflow dispatches it wave-by-wave (same-wave tasks run in parallel on disjoint artefact paths). Typical owners: `design-ui-designer` (tokens, components, screens), `design-ux-designer` (flows), `design-presentation-designer` (slides), `design-brand-strategist` (voice), `design-visual-designer` (logo, CIP, assets).

Each specialist opens its assigned task, does the work, writes the artefact to its engagement path, and appends its result to `executor-reports/{specialist-agent-name}.md` § "Task {NN}: {title}".

### Phase 4: Iter-2 retargeting (on REJECT)

On an iter-2 REJECT, the Workflow's rework loop re-runs ONLY the affected tasks — those where:
- `crit_refs` includes the failing crit-N, OR
- `deliverable_type` matches the rejected artefact (e.g. the verdict says "screen X has wrong button radius" → re-run the screen task AND the button component task if the token drifted).

Only those tasks re-run; the specialist appends `## Iteration 2` to its executor-report (per `engagement-protocol` §4-iter).

## Token propagation safety

Design's biggest iter-2 trap: a token changes (wave 2), but components (wave 3) and screens (wave 4) don't get re-rendered. The plan's `depends_on` must guarantee:

- If a wave-2 token task is re-run on iter-2, every wave-3 component task that consumed that token MUST also re-run, and every wave-4 screen using those components MUST re-render.
- This is automatic IF `depends_on` is wired correctly. Manual audit: trace the dependency graph from the changed token and queue everything downstream.

`tasks/INDEX.md` should make this graph explicit so it's not lost on iter-2.

## Anti-patterns

- **Don't decompose retroactively.** Either at Phase 2.5 or skip (size: S).
- **Don't write `tasks/*.md` content longer than 50 lines.** Spec details belong in `executor-reports/{specialist}.md`.
- **Don't violate sequence.** A screen task with no token dependency = REJECT.
- **Don't put the same `crit-N` in `crit_refs` of >5 tasks.** If a criterion needs that many tasks, sharpen criteria.md (lead-authority, no user touch).
- **Don't make a task's `owner` a lead.** Owners are specialists (the lead plans; the engagement-workflow dispatches).
- **Don't skip `theme` field on UI tasks.** Light-only and both-themes have different acceptance bars; ambiguity here causes iter-2 "we forgot dark mode".
- **Don't number tasks before verifying dependencies.** A non-monotonic `depends_on` (task 05 depends on task 12) hides bugs — re-number after dependency lock.

## What this is NOT

- Not a `task-creator` invocation (dev-only).
- Not validated by dev validators (`task-validator`, `reality-checker`). Lead's Phase 2 self-check is sufficient. Critique/accessibility/ux-review run on the *delivered artefacts*, not on the task files.
- Not a Figma file index — task files describe what to produce, not where the live source is. Live source paths go in the executor report after delivery.

## Cost estimate

For an L engagement with 18 atomic tasks (rebrand + product UI): ≈30-45 min of lead time to draft + self-validate + INDEX.md. Saves ≥2 hours on a single iter-2 reject of token drift (which would otherwise re-run components + screens + accessibility audit). Net positive at any reject rate above ~0.2 — current design baseline is 0.6.