From workflow-skills
Use when a task estimates size 3 or above, 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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/workflow-skills:break-down-taskThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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 s...
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.
3 or above (multi-layer rework, many unrelated files, several behaviors at once)./promote-tasks scored a card LOW with scope exceeds size 5 — split into sub-tasks./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.
The task store is handler-defined (dev_docs/tasks/.task-config.yml; absent → repo-pr). Read it the same way /promote-tasks does:
cat "$(git rev-parse --show-toplevel)/dev_docs/tasks/.task-config.yml" 2>/dev/null
repo-pr (default, or file absent / no handler:) → 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, per commands/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-tasks takes for these.) You may still print the proposed slices so the human can paste them in.<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.
dev_docs/tasks/**/*.md and pick the candidate that triggered this — typically the one most recently flagged needs_refinement with a # promoter: scope exceeds size 5 comment, or the one the user is discussing. If ambiguous, ask which task. Never guess and delete the wrong one.type: epic is a rollup, never a task — don't break it down (see Epics in skills/task/SKILL.md).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 the related_files if you need to judge real scope — the breakdown is only as good as your understanding of the work.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 that are each still ≤ size 2. 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:
2. If a proposed slice still looks like ≥ 3, slice it again (recurse) or pick a finer seam.## Task and ## Acceptance Criteria and check every item maps into exactly one slice.is_blocked_by; there must be no cycle. A slice that depends on two earlier ones lists both (is_blocked_by: [a, b]).2s beat four size-1s. Don't over-shatter — review overhead is real.Score the proposed breakdown HIGH only if all hold:
5 (your judgment, weighing each slice's ## Task steps and related_files).Otherwise it's LOW.
skills/task/SKILL.md), born status: new:
is_blocked_by resolves by slug across dev_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.title and size. Each slice gets a fresh imperative title and its own per-slice size (Fibonacci 1/2/3/5, each ≤ 5) — these are per-slice, never inherited, and size is the whole point of the split. status: new.priority, source_branch, source_pr, tags, and impact from the original unless a slice clearly differs. Set created to today, expires to the original's (or 30 days out). Carry the original's parent if it had one; if the original was itself a meaningful grouping you may instead convert it into an epic (set type: epic and status: active, conforming to the epic shape — see Epics in skills/task/SKILL.md) rather than deleting it, and point each component's parent at the original slug. A parent reference only resolves if the epic file still exists, so this is convert-not-delete — don't invent an epic just to look tidy.related_files scoped to that slice only, not the union.is_blocked_by encodes 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 itself is_blocked_by something 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.## Context (carry the relevant background + a one-line "split from <original-slug>" note), a concrete ## Task for just that slice, and ## Acceptance Criteria (≥ 1 bullet) covering that slice. Split criteria into Code-enforced / User-run where useful, per plan-with-docs.plan-with-docs plan dir (<name>_plan/), keep the components there and follow that plan's unique-numbering rule.type: epic, status: active) instead of deleting — the components' parent references need it to exist, and an epic file must carry a valid epic status. Otherwise remove it (git rm or delete in the working tree); the components now carry all its scope./promote-tasks and plan-with-docs, leave the changes in the working tree for the next git operation (the user, or /do-tasks) to pick up.is_blocked_by edges (a tiny dependency tree), and remind the user to run /promote-tasks to score the new cards and /list-tasks to see the board.Never delete the original on LOW confidence. Instead:
status: needs_refinement and human_approval_requested: true (add if missing).## Open Questions section 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 Questions keeps /promote-tasks from auto-promoting it until resolved./promote-tasks flags oversized cards (scope exceeds size 5 — split into sub-tasks) but never splits them — this skill is how that flag gets resolved.plan-with-docs uses the same slicing judgment and output format; reach for it when planning from scratch, this skill when an existing task outgrew one PR./do-tasks runs the components once /promote-tasks flips them to ready; is_blocked_by keeps them in order.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.
npx claudepluginhub bestdan/workflow-skills --plugin workflow-skillsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.