Tasks

Skill: tasks

Task-breakdown generator: atomic tasks ≤1 day, each a separately reviewable change (≤~500 LOC preferred), with a visible dependency graph and a Definition of Done per task. One task = one focused session = one PR. "Build the feature" is not a task — break it down.

A task file is self-contained. The rule that governs every task body: inline the slice the task actually needs, name where it came from, and keep the link as the fallback for when the slice turns out not to be enough. A task that only points at spec.md §AC-N makes the executing agent go and rebuild the context this breakdown already had — it burns its budget on rediscovery and still misses. Alongside the human-facing markdown, this skill emits tasks.json, the contract the implement engine reads to build its dependency DAG.

Every inlined chunk carries a one-line provenance signature — <file> §<section>, <identifier>, verbatim|abridged, e.g. «spec.md §5, AC-02, verbatim» — never «see the spec». The signature is what makes an inline re-checkable: an inline is a snapshot taken at breakdown time, upstream can move after it, and the source always wins.

Task prose (title / dod, the markdown bodies) follows artifact_language — the tasks.json machine fields (id, layer, deps, acs, files_hint, slug) and tracker states stay English → ../_shared/artifact-language.md. An inlined chunk is quoted verbatim in the language its source artifact is written in; the signature is not translated.

Owner

Tech Lead.

Inputs

• <slug> — feature slug.
• Gate (hard refuse): docs/features/<slug>/spec.md + docs/features/<slug>/sad.md + ≥1 Accepted ADR in adr/. Missing → STOP and point at the producing skill (specify / design / decide-adr).
• Read directly (not via an index): spec §5 AC + §6 NFR, sad §5 module boundaries + §6 runtime + §9 ADR index, each Accepted ADR, and — if present — data-model.md, contracts/openapi.yaml and screens.md (the screen manifest ui tasks cite).
• (Expected) sad.md frontmatter target_surfaces — gates which layers appear (step 4). Absent or empty → warn («surfaces undeclared — re-run design, or proceeding as backend-service») and treat as [backend-service] (→ ../_shared/surfaces.md); never silently emit ui tasks for an undeclared surface.

Protocol

1. Prereq check (hard). spec.md + sad.md + ≥1 Accepted ADR, else refuse with the missing one named.

2. Read upstream directly. Each task will carry the slices it needs, quoted from the source — so read the source text itself, never a paraphrase of it: the quote goes into the file.

3. Read the templates from disk, then scaffold output. Read ./templates/task.md before writing a single task file — its frontmatter keys and its ## section list are the contract, and its <!-- instruction … --> comments are the per-section brief. Same for ./templates/_epic.md and ./templates/tracker.md. Never write a task from memory of what a task file looks like: the self-contained format (the blocks / context_budget keys, the nine sections, the provenance signatures) is younger than most recollections of it, and a remembered shape silently reverts this skill to the link-only tasks it exists to replace. Output: docs/features/<slug>/tasks/ with _epic.md (summary + links + the DAG flowchart), tracker.md (status table), one <task-slug>.md per task. Validate the _epic.md flowchart per ../_shared/mermaid-check.md (render-parse with mmdc if available, else the structural lint; fix before committing).

4. Identify work-items by layer. Generic, stack-agnostic layers: migration (DB) · domain (entities/invariants) · infra (repo/persistence) · app (service/use-case) · ports (handler/API) · ui (UI components / screens / view-state — only when a UI surface is declared) · tests · wiring (composition/DI) · docs. sad.md frontmatter target_surfaces gates which layers appear (→ ../_shared/surfaces.md): a web-frontend / mobile-app / desktop-app surface adds ui tasks; a backend-only feature emits domain/infra/app/ports (no ui); a cli feature app/ports; a worker domain/infra. Each ui task names the existing components / tokens / styling it reuses (from architecture-map.md §Frontend and the docs/design-system.md inventory) — a new component is listed only when no existing primitive fits — and, when docs/features/<slug>/screens.md exists, cites the SCR-NN id(s) + the states it builds (the manifest is the task's screen contract; implement builds to those states). List 8–20 items by size (see ../_shared/size-matrix.md).

5. Atomic check — work size and context size. Each task ≤1 working day. More → split. And atomic in context: count the inlined lines the finished body will carry (the non-empty lines from ## Why (user story) through ## Acceptance criteria) against the context_budget bands — S ≤40 · M ≤120 · L beyond. An L is a split signal: either split the task, or keep it and write the reason on the frontmatter line itself (context_budget: "L" # justified: <one line>). An unjustified L fails the step-13 self-check. A change >~500 LOC is a smell that the task is too wide. Contract-task rule: a task whose content is changing a shared interface/type that existing implementations must satisfy in a statically-checked language (Go, TS, Java, …) is not emitted standalone — it cannot be committed green on its own (the compile-time check breaks every implementer). Fold it into the first implementing task. If a split is still warranted (several implementers), mark the pair a compile-coupled lane: both tasks list the contract file in files_hint (reusing the existing overlap-lane mechanics — no tasks.json schema change), so implement serializes them and may close them with one shared gate + commit.

6. Dependency graph. For each task, deps: [...] — and its exact inverse blocks: [...], the ids waiting on this one, so a task shows what it holds up without the reader reconstructing the graph. Identify parallel branches (e.g. the migration and a pure-domain task can start together). This graph IS the DAG implement will topologically sort into phases.

7. Per-task DoD. Each task is testable: «unit tests for the new validation pass», «migration applies and reverts cleanly», «handler returns the spec'd outcome for AC-03». No subjective «done when I say so».

8. AC refs + files hint. Each task lists the acs it satisfies (spec §5 IDs) and a files_hint — the directories/files it will touch. files_hint lets implement serialize tasks whose file sets overlap, and layer: migration is always serialized (ordered migration sequence); a compile-coupled pair (step 5) shares the contract file across both files_hints for the same reason; layer: ui is not auto-serialized — UI tasks parallelize unless their files_hint overlaps. A migration task's files_hint is the staged pair docs/features/<slug>/migrations/<NN>_* (which implement promotes into the live migrations/ when it runs the task) — not a live migrations/ path.

9. Fill the task body — self-contained, not a link list. Every section of ./templates/task.md is sourced from a named artifact:

   • Place in the sequence ← the DAG (step 6): deps and blocks by id + title, the wave, and the lane it shares (overlapping files_hint / compile-coupled pair).
   • Why (user story) ← spec.md §4 — the US-NN block verbatim, then one sentence on what this task contributes to it.
   • Inlined context ← spec.md §1 committed approach · spec.md §6 NFR + sad.md §11 for the Hard Rules this task must not violate · sad.md §5 for the building block it lives in (boundary + collaborators) · sad.md §6 for the runtime steps it implements, error branches included · the decision line of each Accepted ADR that constrains it · screens.md SCR-NN + the states, for ui tasks.
   • Data delta ← data-model.md — only the entity/columns/constraints/indexes this task touches, plus the staged migration pair for layer: migration. No schema change → the literal «No DB changes.», never an empty section.
   • API contract ← contracts/openapi.yaml — only the operations this task implements or calls, with the request/response fields and error codes it owns. No surface → «Internal — no API surface.»
   • Acceptance criteria ← spec.md §5 — the Given-When-Then of every id in acs, verbatim. The tests assert these; a paraphrase here becomes a wrong test downstream.
   • Edge cases ← the negative branches of those §5 ACs + the sad.md §6 error paths, as a case/behaviour table.

   Record the file you just wrote as the task's file (repo-relative docs/features/<slug>/tasks/<task-slug>.md) — step 11 emits it into tasks.json, and that pointer is the only way implement reaches this body.

   Signature. Each chunk ends with <file> §<section>, <identifier>, verbatim|abridged and the link to the full text. Cutting a long chunk: keep the sentences that change what gets built (the constraint, the number, the branch, the error code), drop narrative and anything belonging to another task, mark the result abridged, keep the link. Budget: only this task's ACs, only the fields and endpoints it touches — a task carrying another task's context is as broken as one carrying none. The template also addresses the executing agent directly: an insufficient or code-contradicting slice means go read the named file, never invent the missing part.

10. Estimate + owner + context budget. estimate S/M/L or hours (how long the work takes); a named owner (or <TBD lead>); context_budget S/M/L — the honest cost of holding this task, measured (not guessed) as the step-5 count: S ≤40 inlined lines and ≤1 extra file to open · M ≤120 lines, 2–4 files · L beyond, carrying its # justified: reason. Adapt estimate to the team's sizing if any; the budget bands are fixed.

11. Emit tasks.json (step contract below) — the same model the markdown reflects, in machine form, at docs/features/<slug>/tasks.json. Every entry carries file, the repo-relative path of the markdown written in step 9; that pointer is what lets implement hand the agent the inlined context instead of sending it back upstream.

12. Optional tracker export. If an issue-tracker MCP is connected (Jira / Linear / GitHub Issues / Redmine — whichever the repo uses), offer to create tickets from _epic.md + the task files. Otherwise provide copy-paste-ready bodies. Never hard-bind to one tracker.

13. Self-check. Every task ≤1 day; DAG acyclic with ≥1 parallel branch where the work allows; blocks is the exact inverse of deps; DoD per task; every task's Inlined context and Acceptance criteria are non-empty; no upstream reference without a provenance signature; every task's inlined-line count sits inside its context_budget band, and every L carries its # justified: reason; every file points at a markdown that exists on disk; acs cover every spec §5 AC; tasks.json validates against the contract.

14. Propose commit + handoff. tasks: <slug> (breakdown + tasks.json). Then emit the stage-handoff block per ../_shared/handoff.md — What I did + Review (tasks/, tasks.json) + Run next — resolve the next stage per .route (the Routes table in ../_shared/size-matrix.md): forward /sdd:plan-tests <slug> (on quick it always collapses to the inline ## Test plan in spec.md), then /sdd:implement <slug>; plan-tests' N/A condition = every task's DoD already names its test — only then skip target /sdd:implement <slug> directly (auto-skip on quick, offered ↳ or on standard, never on full).