Break down task
Use when a task estimates larger than size 5, when a task touches 3+ unrelated subsystems even at or under size 5, when /promote-tasks flags "scope exceeds size 5 — split into sub-tasks", or when the user says a task/card/ticket is "too big", "won't fit in one PR", or asks to "split", "slice", "break down", or "chunk up" existing work.From its SKILL.md
npx -y skills add bestdan/workflow-skills --skill break-down-taskAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
14.3 KB, as published. Nobody here has run it
break-down-task — slice a too-large task into PR-sized components
A task in the loop is supposed to be one task = one PR (size ≤ 5, ~300 lines / ~5 files — see Task size in skills/task/SKILL.md). Sometimes a task that looked small grows, or /promote-tasks flags it scope exceeds size 5 — split into sub-tasks, or the user captured something that was always an epic. This skill takes one such over-sized task, looks for shear points — natural seams to cut along — and, when it can do so with high confidence, removes the original task and writes the component tasks in its place, chained by is_blocked_by so the loop runs them in order.
It is the resolution of the /promote-tasks size gate, and the sibling of plan-with-docs: plan-with-docs slices a fresh idea into tasks; this skill slices an existing task that turned out too big. Both emit canonical task cards (skills/task/SKILL.md) born status: new, so the output feeds the same /promote-tasks → /do-tasks pipeline.
When to use
- A task estimates larger than size
5(multi-layer rework, many unrelated files, several behaviors at once) — too big to capture as one card. - A task touches 3+ unrelated subsystems even while nominally at or under size
5— subsystem count is a split trigger independent of raw line/file count (see Task size inskills/task/SKILL.md). /promote-tasksscored a card LOW withscope exceeds size 5 — split into sub-tasks.- The user points at a specific task/card/ticket and says it's too big, won't fit one PR, or asks to split / slice / break down / chunk it.
- Mid-
/do-tasks, the executor realizes the claimed task is too large to finish in one PR and bails for breakdown.
Not this skill: capturing brand-new follow-up work (/add-task), planning a feature from scratch (plan-with-docs), or scoring existing cards (/promote-tasks). If there is no concrete oversized task yet — just a big idea — use plan-with-docs.
Resolve the handler first
The task store is handler-defined (dev_docs/tasks/.task-config.yml; absent → repo-pr). Resolve handler: from the merged view the same way /promote-tasks does (see commands/task-config.md → "Resolving the handler"):
ROOT="$(git rev-parse --show-toplevel)"
cat "$ROOT/dev_docs/tasks/.task-config.yml" 2>/dev/null # committed config
cat "$ROOT/dev_docs/tasks/.task-config.local.yml" 2>/dev/null # optional gitignored override
Overlay the local override on the committed config — mappings merge recursively, local leaf values win — then resolve handler: from the merged view.
repo-pr(default, or file absent / nohandler:) → the file path below. Fully supported.linear→ the source task is a Linear issue. Do the same analysis, then either (a) convert the original into a parent issue and create the components as child issues under it — leave the original open, it now tracks the children — or (b) create the components as independent issues linked by a relation and cancel the original. Don't cancel an issue that still has children. Use the Linear MCP tools the task commands already use (<linear-mcp>__list_teams,<linear-mcp>__list_issues,<linear-mcp>__save_issue,<linear-mcp>__save_comment— substitute the prefix loaded in your session, percommands/handlers/linear-common.md). Honor the same HIGH/LOW gate — on LOW, leave the issue intact and comment the proposed split for a human.gh-issue/jira→ stop with: "breakdown isn't automated for<handler>; split the issue in the tracker directly." (Same stance/promote-taskstakes for these.) You may still print the proposed slices so the human can paste them in.- Unknown value → stop with: "Unknown task handler
<value>in dev_docs/tasks/.task-config.yml. Run /task-config to fix it."
The rest of this skill describes the repo-pr file path; the analysis (shear points, confidence) is handler-independent.
Identify the source task
- Locate it. If the user named a slug, file, or issue, use that. Otherwise scan
dev_docs/tasks/**/*.mdand pick the candidate that triggered this — typically the one most recently flaggedneeds_refinementwith a# promoter: scope exceeds size 5comment, or the one the user is discussing. If ambiguous, ask which task. Never guess and delete the wrong one. - Skip epics. A file with
type: epicis a rollup, never a task — don't break it down (see Epics inskills/task/SKILL.md). - Read it whole. Frontmatter (
title,priority,size,impact,status,source_branch,source_pr,parent,is_blocked_by,tags,related_files) and the full body (## Context,## Task,## Acceptance Criteria). Open therelated_filesif you need to judge real scope — the breakdown is only as good as your understanding of the work.
Find the shear points
A shear point is a seam where the work naturally separates into pieces that can each ship as an independent, reviewable PR. You are looking for the cuts that yield the fewest, largest slices within the slice budget: target each slice at ≤ size 3, hard cap size 5. Prefer cuts that produce slices which are individually mergeable and leave the system working at each step.
Common seams, roughly in order of preference:
| Seam | Cut along… | Example |
|---|---|---|
| Vertical slice | a thin end-to-end increment of one behavior | "Support CSV export" → first just one column set end-to-end, then the rest |
| Preparatory refactor | a no-behavior-change refactor first, then the change on top | extract a helper / introduce a seam in PR 1, use it in PR 2 |
| Interface then implementation | define the contract (types, API shape, stub) then fill it in | add the endpoint signature + types, then the handler logic |
| Layer (horizontal) | architectural layer | schema/migration → data access → API → UI, one PR each |
| Module / file boundary | independent files or packages that don't share a diff | "update all call sites" → batch by package |
| Read then write | the safe read/observe path before the mutating path | add metrics/logging first, then act on them |
| Happy path then edges | core case first, then error handling / edge cases | implement the main flow, then validation + failure modes |
| Behind a flag | land dark behind a flag, then flip / clean up | ship gated code, then enable + remove the flag |
Rules for good slices:
- Each slice stays within the slice budget above. If a proposed slice exceeds the hard cap, slice it again (recurse) or pick a finer seam.
- MECE. Together the slices cover the entire original scope (no dropped work) with minimal overlap. Re-read the original
## Taskand## Acceptance Criteriaand check every item maps into exactly one slice. - Clean dependency DAG. Ordering between slices is expressed with
is_blocked_by; there must be no cycle. A slice that depends on two earlier ones lists both (is_blocked_by: [a, b]). - Each slice keeps the build green. Prefer cuts where every intermediate PR leaves tests passing and the app working. A "preparatory refactor first" cut is usually the way to achieve this.
- Prefer few, fat slices. A couple of at-target slices beat a swarm of trivial ones. Don't over-shatter — review overhead is real.
Confidence gate
Score the proposed breakdown HIGH only if all hold:
- Every component stays within the slice budget's hard cap (size <= 5; see Find the shear points) — your judgment, weighing each slice's
## Tasksteps andrelated_files. - The slices are MECE against the original scope — nothing dropped, no significant overlap.
- The dependencies form an acyclic DAG and the order makes sense.
- The union of the components' Acceptance Criteria covers the original's Acceptance Criteria.
- You understood the original well enough to slice it (you weren't guessing at what the code does).
Otherwise it's LOW.
Apply
HIGH confidence → replace the original
- Present the proposed breakdown first — a short numbered list (one line per component: title, size, what it covers, what it's blocked by) plus the seam you cut along. Removing the original is destructive (though git-recoverable), so let the user see the split before it lands. Proceed once they're good with it; if the user invoked this expecting an automatic split and the breakdown is clearly HIGH, a brief confirmation is enough — don't belabor it.
- Write the component task files. One file per component, canonical task format (
skills/task/SKILL.md), bornstatus: new:- Slugs must be globally unique because
is_blocked_byresolves by slug acrossdev_docs/tasks/**/*.md. Prefix every component with the original slug:<original-slug>__<short-suffix>(e.g.csv-export__schema,csv-export__api,csv-export__ui) or<original-slug>_part_N. Descriptive suffixes read better in/list-tasks. Check for collisions and bump if needed. - Set each component's own
titleandsize. Each slice gets a fresh imperativetitleand its own per-slicesize(Fibonacci1/2/3/5, each within the slice budget — Find the shear points) — these are per-slice, never inherited, andsizeis the whole point of the split.status: new. - Inherit
priority,source_branch,source_pr,tags, andimpactfrom the original unless a slice clearly differs. Setcreatedto today,expiresto the original's (or 30 days out). Carry the original'sparentif it had one; if the original was itself a meaningful grouping you may instead convert it into an epic (settype: epicandstatus: active, conforming to the epic shape — see Epics inskills/task/SKILL.md) rather than deleting it, and point each component'sparentat the original slug. Aparentreference only resolves if the epic file still exists, so this is convert-not-delete — don't invent an epic just to look tidy. related_filesscoped to that slice only, not the union.is_blocked_byencodes the order: the root slice(s) have none within the breakdown; each later slice lists the slug(s) it depends on. If the original was itselfis_blocked_bysomething upstream, every root of the breakdown DAG (each component with no blocker inside the breakdown) inherits those upstream blockers — not just one — so the chain stays connected and no parallel root runs prematurely.- Body:
## Context(carry the relevant background + a one-line "split from<original-slug>" note), a concrete## Taskfor just that slice, and## Acceptance Criteria(≥ 1 bullet) covering that slice. Split criteria into Code-enforced / User-run where useful, perplan-with-docs.
- Slugs must be globally unique because
- Place the files. Same directory as the original. If the original lived in a
plan-with-docsplan dir (<name>_plan/), keep the components there and follow that plan's unique-numbering rule. - Remove or convert the original task file. If you kept it as a thin epic parent (step 2), convert its frontmatter to the epic shape (
type: epic,status: active) instead of deleting — the components'parentreferences need it to exist, and an epic file must carry a valid epicstatus. Otherwise remove it (git rmor delete in the working tree); the components now carry all its scope. - Don't commit, don't open a PR. Like
/promote-tasksandplan-with-docs, leave the changes in the working tree for the next git operation (the user, or/do-tasks) to pick up. - Report. Print the original slug and its fate (removed, or converted to epic), the new component slugs with their
is_blocked_byedges (a tiny dependency tree), and remind the user to run/promote-tasksto score the new cards and/list-tasksto see the board.
LOW confidence → don't destroy anything
Never delete the original on LOW confidence. Instead:
- Leave the original file in place; set
status: needs_refinementandhuman_approval_requested: true(add if missing). - Append your partial proposal as an
## Open Questionssection in the original body — the candidate slices you found, where you got stuck (e.g. "couldn't tell if the migration must precede the API change"), and what a human needs to decide. The presence of## Open Questionskeeps/promote-tasksfrom auto-promoting it until resolved. - Report what's blocking a confident split so the human can answer, then re-run.
Relationship to the rest of the loop
/promote-tasksflags oversized cards (scope exceeds size 5 — split into sub-tasks) but never splits them — this skill is how that flag gets resolved.plan-with-docsuses the same slicing judgment and output format; reach for it when planning from scratch, this skill when an existing task outgrew one PR./do-tasksruns the components once/promote-tasksflips them toready;is_blocked_bykeeps them in order./assess-taskprofiles a task'scomplexity+scope— a useful sizing signal when you're unsure whether a card is over the size-5line and worth splitting at all. Advisory only; the shear-point and confidence judgment above stays the deciding factor.
Legacy migration preflight
Before scanning, if a legacy dev_docs/todos/ directory exists, run the Legacy migration prompt from skills/task/SKILL.md to move it to dev_docs/tasks/, then continue.