task-dag

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/<slug>/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/<slug>/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/<slug>/tasks/, where <slug> 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-<task-slug>.md (skeleton, one per task)
• plans/team-invitations/tasks/T-002-<task-slug>.md
• …

Honor any explicit output path the user provides.

6. Write tasks/index.md

This file is the human-reviewable DAG. Structure:

# <Feature Name> — Task DAG

**Source design:** <relative path to design.md>
**Granularity:** medium  *(or fine / coarse, whichever was used)*
**Last updated:** <YYYY-MM-DD>

## 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/<slug>/tasks/T-NNN-<task-slug>.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