--- name: task-dag description: Decompose a technical design document into a DAG (directed acyclic graph) of work tasks. Use this skill whenever the user asks to "break down" / "decompose" / "split up" a design into tasks, create a task DAG, sequence the work, or build a task list with dependencies. Trigger on phrases like "decompose the design at … into tasks", "break this design into a task DAG", "create the task list with dependencies", "what's the work breakdown for this design", "sequence the tasks for …", "decompose into a DAG", "build the work plan for the design". This is the step *after* a technical design — it produces a human-reviewable DAG (index.md with Mermaid + table) plus skeleton task files (one per task, with frontmatter), which the `task-specs` skill later fleshes out into full per-task specs. --- # Task DAG Generator Decompose a technical design document into a DAG of tasks that coding agents can execute. A good task DAG answers: **what's the smallest set of independently-mergeable units that, executed in dependency order, deliver the design — and what depends on what?** The DAG itself is the canonical view of the work; the per-task skeleton files are the source of truth for dependency edges (so the downstream `task-specs` skill and coding agents can query them). ## When this skill triggers Use this skill for any request that boils down to "decompose this design into tasks." Common phrasings: - "Decompose the design at `plans//design.md` into tasks" - "Create the task DAG for " - "Break this design into a task list" - "Sequence the work for this design" - "What's the work breakdown?" The user may pass a granularity argument: `fine`, `medium` (default), or `coarse`. Treat the argument as load-bearing — it materially changes how many tasks you produce and how thick each one is. If the user is asking for a *design* (architecture, file paths, contracts), use `tech-design` instead. If they're asking to *flesh out* an existing DAG into full per-task specs, use `task-specs`. ## Workflow ### 1. Read the inputs Locate the design doc. If the user passed a path (`plans//design.md` or otherwise), read that. If they pasted content inline, work from it. If they gestured at "the design we just wrote," look in `plans/` for the most recent `design.md`, or ask which one. Also read the sibling `prd.md` if present — it's the source of truth for the *why* behind the work, which matters when you have to decide whether two related changes are one task or two. ### 2. Recall from Hindsight memory (best-effort) If Hindsight memory tools are available in this session, query them before decomposing. - Call `mcp__plugin_hindsight-memory_hindsight__agent_knowledge_recall` with a query like "task decomposition patterns for this repo" or "typical task shape for ". - If a relevant page comes back, read it via `mcp__plugin_hindsight-memory_hindsight__agent_knowledge_get_page`. Prior runs may have recorded conventions like "auth changes in this repo always touch these 4 places" — that's the kind of signal that should shape decomposition. Recall is best-effort. If unavailable or empty, proceed normally. ### 3. Decompose into tasks (granularity matters) Read the design end-to-end before splitting. The components / data model / APIs / patterns-to-reuse sections give you the natural seams. Apply the granularity rules below. Each task must: - **Be a vertical slice.** It ships its own tests, types, and any required scaffolding. Don't make "write the model" one task and "write the tests for the model" another — that creates a task that leaves the system in a broken state when merged alone. - **Leave the system in a working state.** After this task lands, the repo still builds, tests still pass. - **Be independently testable.** It has clear acceptance criteria the coding agent can verify. - **Match the granularity target.** Surface tasks you had to split or merge to honor the size — that signal helps the user tune. #### Granularity heuristics | Granularity | Files touched | Acceptance criteria | Shape | |-------------|---------------|---------------------|-------| | `fine` | 1–2 | 1–2 | Single function / single file change. Many tasks, very tight DAG. Best when the team wants every step reviewable, or when many agents will work in parallel. | | `medium` (default) | 2–5 | 2–4 | One coherent unit (model + migration + tests; endpoint + handler + tests). Mergeable on its own. | | `coarse` | 4–10 | 3–6 | Larger vertical slice (full CRUD for a resource, full feature flag rollout). Best when one agent will own a slice end-to-end. | The thresholds are guidance, not a contract. If the design has a 6-file slice that can't sensibly be split, leave it as one `medium` task and note the deviation in the index. ### 4. Identify dependencies For each task, list the tasks that must complete before it can start. Aim for the **minimum-edge** DAG — don't invent dependencies that aren't real. Two tasks that touch unrelated files have no edge, even if they're conceptually adjacent. Common honest dependency patterns: - "Migration must exist before the model that uses it" → model depends on migration. - "Endpoint depends on the handler it routes to" → endpoint depends on handler. - "Test fixtures depend on the model under test" → tests depend on model. Confirm the DAG is acyclic. If you've drawn a cycle, you've decomposed wrong — back up and re-split. ### 5. Confirm output location Default to `plans//tasks/`, where `` matches the design's directory. So a design at `plans/team-invitations/design.md` produces: - `plans/team-invitations/tasks/index.md` (DAG view) - `plans/team-invitations/tasks/T-001-.md` (skeleton, one per task) - `plans/team-invitations/tasks/T-002-.md` - … Honor any explicit output path the user provides. ### 6. Write `tasks/index.md` This file is the human-reviewable DAG. Structure: ```markdown # — Task DAG **Source design:** **Granularity:** medium *(or fine / coarse, whichever was used)* **Last updated:** ## Summary 1–2 sentences. How many tasks, what's the longest chain, anything notable about the shape (heavy parallelism? long critical path?). ## DAG ```mermaid graph TD T001[T-001: User model + migration] T002[T-002: Invitation model + migration] T003[T-003: POST /invitations handler] T001 --> T003 T002 --> T003 ... ``` ## Tasks | ID | Title | Depends on | Files (est.) | 1-line summary | |-------|--------------------------------|------------|--------------|----------------| | T-001 | User model + migration | — | 3 | Adds `User` type + migration + unit tests. | | T-002 | Invitation model + migration | — | 3 | Adds `Invitation` type + migration. | | T-003 | POST /invitations handler | T-001, T-002 | 4 | New endpoint accepting 1–50 emails. | | … | … | … | … | … | ## Notes on shape Things worth surfacing to the human reviewer: - Tasks I had to split or merge to honor the granularity target (and why) - Critical path length and any unexpectedly serial sections - Tasks where the design left open questions that downstream `task-specs` will need to resolve ``` The Mermaid diagram is canonical for visual review. The table is for quick scanning. Keep them in sync — if you add a task, add it to both. ### 7. Write skeleton task files One file per task, at `plans//tasks/T-NNN-.md`. The slug is a short kebab-case derivative of the title (e.g., `user-model`). Each skeleton has YAML frontmatter and a one-line body: ```markdown --- id: T-001 title: "User model + migration" depends_on: [] status: pending estimated_size: medium --- Adds the `User` type and its initial migration, with unit tests. (Full spec to be written by `task-specs`.) ``` Frontmatter fields: - `id` — `T-NNN` format, sequential, stable. Never reuse an ID for a different task. - `title` — human-readable, ~5–8 words. Matches the table in `index.md`. - `depends_on` — list of task IDs that must complete before this task can start. Empty list (`[]`) for leaf tasks. - `status` — always `pending` at this stage. `task-specs` and downstream coding agents will update this. - `estimated_size` — the granularity bucket actually used for this task (`fine` / `medium` / `coarse`). Usually matches the run-level granularity, but call out individual tasks that ended up larger or smaller. The skeleton body is intentionally thin — one line. The downstream `task-specs` skill will replace it with the full spec while keeping the frontmatter intact. Don't write the full spec here; that's a separate step where the codebase exploration happens. ### 8. Persist learnings to Hindsight (best-effort) If Hindsight is available *and* the decomposition surfaced a reusable pattern — "in this repo, an HTTP endpoint task always pairs with a handler task and a test fixtures task" — write or update a page via `mcp__plugin_hindsight-memory_hindsight__agent_knowledge_create_page` (or `_update_page`). Keep pages tight: one decomposition pattern per page, with concrete examples. Don't dump feature-specific task lists into Hindsight — those belong only in `tasks/`. ### 9. Surface the file and the shape Tell the user where the artifacts live, in one or two sentences: *"Wrote the DAG to `plans/team-invitations/tasks/index.md` (12 tasks, longest chain T-001 → T-003 → T-007 → T-011). Skeleton task files are in the same directory. Run `task-specs` next to flesh them out."* If you had to make notable decomposition judgment calls (merged two design components into one task; split a single component into three; chose to leave an ambiguous boundary as one task) — flag them so the user can correct them before downstream skills lock the shape in. ## Quality bar The DAG is the document that determines whether downstream coding agents can pull no-dep tasks and drain the queue in parallel. Aim for: - Real dependencies, not invented ones — every edge must have a clear "X needs Y to exist first" reason - Vertical slices — every task ships tests - Acyclic — verify before writing - Granularity matched to the target — neither padded out nor crammed - Skeleton frontmatter that downstream tools can parse without falling back to YAML edge cases Things to avoid: - "Setup" or "scaffolding" tasks that don't ship working code — fold these into the first real task - "Write tests for T-001" as a separate downstream task — tests belong inside the task that introduces the code under test - A flat DAG where every task depends on every previous one — that's just sequential numbering, not real dependency analysis - A wide DAG where leaves don't connect — every task should have a real reason to exist, traceable back to the design - Inventing tasks the design doesn't justify — if the design is silent on something, surface it as a note instead of guessing a task into existence