--- name: breakdown description: > Decompose feature into atomic tasks — 1 task per agent. Use AFTER /design and BEFORE /build-brief. Step 3 of 7-step workflow. Maps to H3 (First Things First). user-invocable: true argument-hint: "[--persist ] [feature or PRD to decompose]" allowed-tools: ["Read", "Glob", "Grep", "Write", "AskUserQuestion"] prev-skill: design next-skill: build-brief --- # Step 3: Plan (หั่นงานเป็นชิ้นเล็ก) **Habit**: H3 — Put First Things First | **Anti-pattern**: One giant prompt that tries to do everything at once ## Process 1. **Read the requirements/design**: Load PRD or design decisions from previous steps. 2. **Decompose into atomic tasks** (1 task = 1 focused unit of work): ``` ## Task List 1. [ ] [Task name] — [1-sentence description] | Files: [list] | Depends on: [none or #N] 2. [ ] [Task name] — [1-sentence description] | Files: [list] | Depends on: [#1] ... ``` For backlog-bound work, prefer vertical slices: each task should deliver a thin but complete path that can be verified or demonstrated on its own. Avoid horizontal layer tasks (`schema only`, `API only`, `UI only`) unless that layer is independently useful and has its own acceptance criteria. A good issue describes end-to-end behavior, not a list of implementation layers. 3. **Prioritize** by importance, not interest: - Q1 (Urgent + Important): Blocking dependencies, security fixes - Q2 (Important, Not Urgent): Core features, tests, docs - Q3 (Urgent, Not Important): Nice-to-have polish - Q4 (Neither): Skip entirely 4. **Identify parallel work, delegation readiness, and classify orchestration**: Tasks with no dependencies can run simultaneously. Also classify whether a task is ready for agent pickup or still needs human input. | Type | When | Isolation | | ------------------- | ---------------------------------------------- | ------------------------------------- | | `sequential` | Output of A feeds input of B | Run after dependency completes | | `parallel-safe` | Tasks touch completely different files | Same repo, concurrent execution | | `parallel-worktree` | Tasks touch overlapping files or shared config | Each agent gets isolated git worktree | Produce an orchestration table for the task list: ``` | Task | Type | Isolation | Depends On | |------|------|-----------|------------| | T1 | parallel-worktree | own worktree | none | | T2 | parallel-safe | same repo | none | | T3 | sequential | - | T1, T2 | ``` Add a readiness column when the task list may be filed into a backlog: | Readiness | Use when | | --- | --- | | `ready-for-agent` | The task has success criteria, scope boundaries, and enough context for an agent to pick up without asking the filer | | `ready-for-human` | The task needs human judgment, access, design approval, or manual verification before implementation | | `needs-info` | The task is not yet implementable because a requirement, owner, environment, or acceptance criterion is missing | If `docs/agents/triage-labels.md` exists, map these canonical states to the repo's real issue labels before recommending issue filing. 5. **Token-efficient parallel design** (for `parallel-safe` and `parallel-worktree` tasks): Claude Code's fork agents share a byte-identical prompt prefix with their parent, achieving ~90% input token savings. Apply this principle when designing parallel tasks: - **Maximize shared context**: Group tasks that read the same files and share the same architectural understanding. Their `/build-brief` context sections will overlap, and the shared prefix stays cached. - **Minimize divergence point**: Put the task-specific instruction LAST in the agent prompt. Everything before it is the shared prefix that gets cached. - **Avoid redundant reads**: If 3 agents all need to read `schema.prisma`, include it in the shared brief rather than having each agent read it independently (3x the token cost). | Pattern | When | Token Efficiency | | ----------------------------- | --------------------------- | ---------------------------------------------- | | Sequential (no sharing) | Tasks depend on each other | 1x (baseline) | | Parallel, independent briefs | Tasks touch different areas | ~1.3x (overhead from duplicate system prompts) | | Parallel, shared prefix brief | Tasks share context | ~0.3x (90% cache hit on shared prefix) | This step is most valuable for 3+ parallel tasks. For 2 tasks, the overhead of optimizing the prefix rarely pays off. 6. **Lazy Parallelism Gate**: Before spawning parallel agents, ask: - Can I do this sequentially in ≤5 tool calls? If yes, sequential is cheaper. - Are the tasks meaningfully disjoint (different files, different concerns)? - Will coordinating results add complexity that outweighs time savings? Parallel agents have overhead: context loading, coordination, result merging. Only parallelize when decomposition is genuinely independent and substantial enough to justify the cost. 7. **Scope guard**: For each task ask — "Is this in scope? Will this prevent future problems (Q2) or is it gold-plating (Q4)?" 8. **H3 Checkpoint**: "Am I doing what's important, or what's interesting?" ## Rule of Thumb - If a task touches >5 files, break it down further - If you can't describe a task in 1 sentence, it's too big - If tasks have circular dependencies, redesign ## Handoff - **Expects from predecessor** (`/design`): Architecture decisions and constraints - **Produces for successor** (`/build-brief`): Prioritized task list with dependencies and file paths - **Backlog-bound tasks**: When a task in the produced list will sit ≥7 days before pickup (or filer ≠ picker), recommend filing an issue using the repo's tracker contract if `docs/agents/issue-tracker.md` exists; otherwise default to GitHub issue wording. Use [`guides/templates/agent-brief-template.md`](../../guides/templates/agent-brief-template.md) for the durable issue spec. Habit-mapped variant of the pattern from [mattpocock/skills](https://github.com/mattpocock/skills). - **Issue tracking comments**: When the user asks an agent to pick up, track, or close work through an issue, draft pickup/progress/completion comments using [`guides/templates/issue-tracking-comments.md`](../../guides/templates/issue-tracking-comments.md). Do not auto-post, auto-label, or auto-close unless the user or repo tracker contract explicitly allows it. ## Optional Persistence (`--persist `) When invoked with `--persist `, this skill writes its task breakdown to `docs/specs//tasks.md`, and the `SKILL_OUTPUT:breakdown` block lives in that file (not the conversation). Without the flag: no file writes and no block (byte-identical filesystem behavior to v2.14.3; conversation-block emission was removed in v2.21.39 per [#375](https://github.com/pitimon/8-habit-ai-dev/issues/375)). For the canonical convention (slug regex `^[a-z0-9][a-z0-9-]{1,63}$`, conflict policy, YAML frontmatter format, error message rules, ID-linkage `Task #N` guidance), load `${CLAUDE_PLUGIN_ROOT}/guides/persistence-convention.md`. ID-linkage tip: when persisting, format each task as `Task #N implements: Decision-X (FR-Y)` to cite the design decision and PRD requirement it satisfies. This enables deterministic Coverage and Inconsistency passes in `/consistency-check`. IDs are recommended, not required. ## When to Skip - Single-file change with no dependencies — nothing to decompose - Bug fix with obvious root cause and single touch point - Task already broken down in an external tracker (Linear, Jira, GitHub Project) ## Definition of Done - [ ] Each task describable in 1 sentence — if not, break it down further - [ ] Dependencies mapped (no circular dependencies) - [ ] Parallel work identified — independent tasks marked for concurrent execution - [ ] Tasks prioritized by importance (Q2 > Q1 > Q3, Q4 eliminated) - [ ] No task touches more than 5 files - [ ] Orchestration classification assigned to each task (sequential/parallel-safe/parallel-worktree) - [ ] Backlog-bound tasks classified as `ready-for-agent`, `ready-for-human`, or `needs-info` - [ ] Backlog-bound tasks are vertical slices unless a horizontal task is independently verifiable ## Structured Output Block **Emit this block only into the persisted `docs/specs//tasks.md` file when `--persist` is used** — never append it to the conversation response (the HTML comment renders as visible noise in Codex; see [`guides/structured-output-protocol.md`](../../guides/structured-output-protocol.md) §"Emission gate"). It is machine-readable evidence for `/cross-verify`. The fenced block below is the **file template**: Regardless of persistence, end your conversation output with the plain-text line `[/breakdown] complete` — see [`guides/structured-output-protocol.md`](../../guides/structured-output-protocol.md) §"Completion signal". ``` [/breakdown] COMPLETE SKILL_OUTPUT:breakdown ``` Place this at the very end of the persisted `tasks.md` file, after all human-readable content. ## Further Reading See [Step 3 wiki page](../../docs/wiki/Step-3-Breakdown.md) for deeper walkthrough, examples, and common pitfalls. Load `${CLAUDE_PLUGIN_ROOT}/guides/templates/task-list-template.md` for the output template. Load `${CLAUDE_PLUGIN_ROOT}/habits/h3-first-things-first.md` for the full H3 principle and examples. Load `${CLAUDE_PLUGIN_ROOT}/guides/orchestration-patterns.md` for worktree isolation and context boundary patterns. Load `${CLAUDE_PLUGIN_ROOT}/guides/structured-output-protocol.md` for the structured output block format specification. Load `${CLAUDE_PLUGIN_ROOT}/guides/persistence-convention.md` when `--persist ` is used (canonical spec for opt-in persistence to `docs/specs//tasks.md`). Load `${CLAUDE_PLUGIN_ROOT}/guides/project-context-contract.md` when repo-local issue-tracker, triage-label, or domain context files are present.