Use in conjunction with planning.Plan Determines direction and constraints (what to build, Acceptance criteria).This skill Determines how to execute: size, slices, dispatch, and verification.
When to Use
Invoke when encounteringany implementation work that needs to be split, verified, or coordinated:
- Multi-file feature implementation
- Refactoring across multiple files
- About to write more than about 100 lines of code
- Executing planned tasks (from any planning source, see Inputs)
- Cross-cutting changes (analytics sweep, i18n pass, library migration)
Skip only in the following cases:
- Tiny edits where the size gate determines XS (1 Acceptance criterion, 1 concern, diff <30 lines)
- Pure documentation / config changes that do not involve code logic
Inputs
- A task or spec from any planning source: the built-in Plan,
planning-with-files'stask_plan.md、docs/specs/<topic>/underspec-designspec, or a task description given directly by the user. This skill does not care how the task was originally produced. - Acceptance criteria: the criteria for determining that this work slice is "done".
If Acceptance criteria are missing or vague, go back to planning before continuing implementation. Implementation must have a clear goal.
Step 1: Size Gate
Judge along three dimensions; when the dimensional conclusions are inconsistent,take the higher size：
| Size | Acceptance criteria | Distinct concerns | Est. diff lines | Skill behavior |
|---|---|---|---|---|
| XS | 1 | 1 | <30 | Skip this skill, write directly |
| S | ≤2 | 1–2 | 30–100 | Apply execution discipline, do not split slices |
| M | ≤3 | Multiple concerns within a single feature | 100–300 | Choose slicing strategy + single writer + execution discipline |
| L | 4–6 | Cross-component | 300–800 | Choose slicing strategy + Evaluate parallel dispatch + execution discipline |
| XL | >6 | Across independent subsystems | >800 | Go back to plan. is too large to complete within a single entry |
Here "concern" refers to a cohesive unit of responsibility: a component, module, or an independent behavior.
**Why take the higher size when dimensions are inconsistent:** underestimating size (treating a true L as M) creates merge conflicts and broken intermediate states midway. Overestimating size only costs a bit more process overhead. The two costs are asymmetric, so lean conservative.
Example:
- "Add 12 analytics events across 12 files, 2 lines each" → AC=1, concerns=1 (analytics), <30 lines → XS
- "One SwiftUI View, 400 lines, 5 subviews + state" → AC=3, concerns=1, >300 lines → M(diff lines raise the size)
- "Refactor auth middleware + update 3 callers + add tests" → AC=4, cross-component, about 400 lines → L
Step 2: Pick Slicing Strategy
Run this decision tree from top to bottom; the first matching branch is the result.
Q1: Is this greenfield's 0→1 first landing? → Walking Skeleton: A very thin Vertical path through all layers (data → service → UI → test), just enough to prove the architecture connects. Thicken it later.
Q2: Is this "modifying the same kind of thing in many places" (analytics sweep, i18n, lint pass, mass refactor, design system rollout)? → Horizontal sweep: Same layer, multiple files, one cohesive change. Group by logical group, one commit each.
Q3: Is this a large-scale architecture migration (UIKit→SwiftUI, sync→async, framework swap)? → Branch by Abstraction: First introduce a temporary abstraction layer, migrate implementations under the abstraction one by one, then remove the old path. In form it leans Horizontal, but it is explicitly transitional.
Q4: Is this adding a new self-contained feature, or fixing a bug? → Vertical slice: Put model + business logic + view + tests into one cohesive change. It is the default choice for "add a new X" work in an existing codebase.
Fallback：Vertical slice
Common confusions: "Vertical vs horizontal" is the slicing axis; "serial vs parallel" is the number of writers. The two are orthogonal: Vertical slices can be dispatched in parallel (three independent bugs fixed in three separate files), Horizontal sweeps are usually executed serially.
Step 3: Parallel Dispatch / Step 3: Parallel Dispatch (L scale only)
XS / S / M skip this section; they are executed by a single writer.
For L scale, decide whether to dispatch slices to parallel subagents.
The Iron Law / The Iron Law
Only wheneach slice has independent input and independent outputis the slice plan valid. If two slices may collide: same file, shared data structure, or shared in-flight state, they cannot be parallel. Merge them into one writer, or execute serially.
3.1 Slice-ability Check / Slice-ability Check
Ask: can this task be cut into several pieces whose inputs and outputs do not overlap?
- ✅ "Fix three independent bugs in three different files, each bug has its own test" → fully independent
- ✅ Greenfield: split store, service, ui into different slices → only holds when there is no shared in-flight state
- ❌ "Refactor utils.ts and update all callers" → cascading edits, serial
- ❌ "Add retry to exec, then migrate callers to use it" → pipeline, not parallel
If not,terminate parallel dispatchand continue with a single writer.
3.2 Draft File Assignments / Draft File Assignments
For each candidate slice, list:
- the files it creates / modifies / deletes
- what input it needs from other slices (paths, signatures, data shapes)
- what output it produces (diff, new files, state change)
3.3 Collision Check → Merge / Collision Check → Merge
For each file that appears in multiple slices:
- Even if it is just append-only editing of the same file, merge into one writer (concurrent edits to adjacent lines produce conflicts)
- Semantically overlapping edits, also merge
3.4 Size Filter / Size Filter
Estimate the diff lines of each remaining slice:
- <50 lines → Remove from dispatch; main Agent handles it inline. Dispatch cost (worktree, context, merge) exceeds the benefit
- 50–150 lines → dispatch candidate
- >150 lines or architectural → dispatch, and annotate that slice with "stronger reasoning model at xhigh effort"
**Minimum-slices gate:** If, after filtering, there are fewer than 3 dispatchable slices,terminate parallel, and the main Agent handles them serially. With fewer than 3 writers, the process cost exceeds the parallel benefit.
3.5 Output Contract + Verify Command Per Slice / Output Contract + Verify Command Per Slice
For each dispatched slice, decide:
- Output format: What format the subagent must return (unified diff + rationale / full file + role / config section verbatim / test file + requirement map)
- Verify command: What the main Agent must run after the diff is returned (
npm test -- path、tsc --noEmit, build of the affected package, minimal smoke test) - Handoff block(mandatory): Every dispatched subagent must, in its reply, at theabsolute endoutput the structured handoff block from Section 4.8, placed after that slice's dedicated output. The next slice reads this block, not the preceding process trace.
Without an output format, the subagent will dump verbose context, canceling out the dispatch benefit. Without a verify command, the main Agent is blindly trusting the subagent's conclusions and merging. Without a handoff block, the next slice has nothing to carry forward besides the file diff; discovered issues, commands run, and process deviations are all lost.
3.6 Emit the Dispatch Plan / Emit the Dispatch Plan
| Slice | Writer | Model | Files | Depends on | Output format | Verify |
|---|---|---|---|---|---|---|
| 1 | subagent | inherit | src/x.ts |
— | diff + rationale | npm test -- x |
| 2 | subagent | inherit | src/y.ts |
slice 1 signature | diff + rationale | npm test -- y |
| 3 | main Agent | — | src/z.ts |
slice 1 complete | (inline) | npm test |
**Model column contract:** By default write inherit, meaning the subagent uses the main Agent's current model. Override only when the caller has a clear reason: the user specified a model, the slice has the architecture attribute and needs stronger reasoning and xhigh effort, or the slice is very mechanical and can be downgraded to a cheaper model. Unless the user names a specific model, write overrides using neutral phrasing (e.g., stronger reasoning model, xhigh effort）。
The main Agent dispatches parallel slices to subagents in a single message: one dispatch per slice, with each writer isolated in its own git worktree. Slices with dependencies execute after their dependencies complete.
Step 4: Execution Discipline / Step 4: Execution Discipline (Per Slice)
Applies toeveryslice executed through this skill: single writer or dispatched writer alike. (XS work bypasses this skill per Step 1, so the 4.1 loop only covers S and larger.)
4.1 Increment Cycle / Increment Cycle
Implement → Test → Verify → Commit → Handoff → Next slice
This is the core loop. Every slice must run the full loop before moving to the next step.
- Implement: Implement the smallest but complete functional increment in this slice
- Test: Run the relevant test suite, or per
test-driven-developmentwrite the failing test first - Verify: tests pass, build succeeds, type checks are clean, complete a manual check when needed
- Commit: one atomic commit per slice (for commit message rules see
git-workflow） - Handoff: output the structured handoff block (Section 4.8). A dispatched subagent slice includes it as the last part of its returned reply; for an inline slice, the main Agent writes it to the conversation record before moving to the next slice
- Next slice: carry forward the handoff block, not the process trace
After each slice ends, the system must be in a working, testable state. Do not leave a half-finished slice.
4.2 Simplicity First
Before writing code, first ask:"What is the simplest thing that can work?"
After writing, self-review:
- Can this code be less?
- Is each abstraction carrying complexity forthistask, or is it carrying complexity for an imagined future?
- Three lines of similar code are better than premature abstraction
This is consistent with the root principle "don't add features, refactor, or introduce abstractions beyond what the task requires".
4.3 Scope Discipline
Only touch what the task requires. Do not:
- "Clean up along the way" by changing code next to it
- Refactor imports in files you did not modify
- Modernize syntax in files you are only reading
- Delete comments you do not fully understand
If you find something outside the task scope that is worth improving,record it, but do not fix it：
NOTICED BUT NOT TOUCHING:
- src/utils/format.ts has an unused import (unrelated to this task)
- Auth middleware could use better error messages (separate task)
At the end of the slice, tell the user and let the user decide whether to open a separate task.
4.4 Keep Compilable Between Slices
After each slice commit, the project must be able to build, and existing tests must pass. Do not leave a broken codebase between slices. If a slice naturally produces a broken intermediate state, it means the slice boundary was cut wrong and needs to be recut.
4.5 Rollback-Friendly
Each slice's commit should be independently revertible.
- Additive changes (new files, new functions) are easy to revert
- Keep modifications minimal and focused
- DB migrations must have rollback migrations
- Never delete-and-replace in the same commit: split into two commits
For the Atomic commit rule, see git-workflow; this rule adds a delete-replace constraint on top of it.
4.6 Risk-First Execution Order
When multiple slices do not block each other (no inter-slice dependency forces an order), do the most uncertain slice first. If the highest-risk slice fails, it can be discovered before investing in dependent work.
Examples:
- Do WebSocket integration first, then do the features that depend on it
- Integrate the Third-party SDK first, then do the features built on top of it
- Try the unverified platform API first, then write the production logic that depends on it
Risk-first isexecution order, not a slicing axis. It can be combined with Vertical slice or Horizontal sweep.
4.7 Don't Repeat Useless Commands
If a command (build, test, type check) has already run successfully and the code has not changed since, do not rerun it. Repeatedly executing on unchanged code adds no information and only consumes context. Only rerun after an edit may affect the command's result.
4.8 Per-Slice Handoff Schema
Every slice, whether a dispatched subagent or inline, ends with a structured handoff block. The next slice reads this block, not the preceding process trajectory. Externalize slice state into a fixed-shape document, replacing "the agent remembers what just happened" with parseable handoff information.
Schema(markdown, copy this shape verbatim):
## Handoff: <slice-name>
**completed**:
- <bullets — what landed, name files where useful>
**not_completed**:
- <bullets — attempted but didn't finish, each with one-line reason>
**commands_executed**:
- `<cmd>` → exit <code> [<one-line outcome>]
**issues_found**: <bullets, or `none`>
**procedure_compliance**: <`followed` | `deviated: <reason>`>
Filled-in example(worked example: hypothetical slice 1 of the validation-contract feature):
## Handoff: validation-contract-frontmatter
**completed**:
- Added optional `validationContract:` field to `SpecMeta` in `src/types.ts`
- Updated `src/build/generate-catalog.ts` to surface the field into `dist/catalog.json`
- Added presence + absence cases to `tests/catalog.test.ts`
**not_completed**:
- Web UI rendering of the field — out of slice scope; next slice owner
**commands_executed**:
- `npm test -- catalog` → exit 0 [3 tests pass]
- `npm run build` → exit 0 [dist/catalog.json regenerated]
**issues_found**:
- `tests/fixtures/` naming convention isn't documented in the test file (surface only; not fixing here)
**procedure_compliance**: followed
Why this shape:
commands_executedWith exit codes: saying only "tests pass" without recording the command does not constitute an audit trailprocedure_complianceMake deviations explicit (e.g.deviated: created tests/fixtures/foo.json without prior approval), the next slice owner must be able to see it directly rather than infer itnot_completedFields must be retained even if empty; leaving a field empty when something was deferred is a discipline failure- The five fields are the minimal set that preserves information across a model switch; extending this schema requires updating the dispatch prompt templates in sync
Flow (writer → broker → reader): Slice N (writer) writes the handoff block at the end of its response, the main Agent (broker) copies it verbatim into the dispatch prompt for slice N+1 (reader), alongside the N+1 spec and verify command; the subagent receives it as data, does not rewrite or summarize it, and there is no direct channel between slices. For inline slices, the main Agent plays all three roles at once: it writes the block into the transcript, reads it back when the next slice begins, the discipline is the same, only the dispatch process is omitted.
**Ordering discipline:** the handoff must be filled in after Verify completes successfully. The handoff records what has already passed, not what was attempted. If verify fails, this slice is not yet complete; fix or roll back first, then write the handoff.
Prohibitions / Must Not (the scope of each Slice Worker)
The execution discipline above describes the rules positively. Here are the corresponding negative rules for each worker (subagent or main-Agent inline) executing a single slice.
- A Worker must not declare "feature done". Slice-level "done" only means this slice's diff compiles, tests pass, and the handoff is filled in. Whether the entire feature satisfies the Acceptance criteria is judged by
verification-before-completion; after PR Ready it is further judged bydeep-review, not self-certified by the worker. A worker declaring "done" on its own triggers the Self-Evaluation Bias that this workflow is meant to avoid. - A Worker must not refactor adjacent code outside the assigned slice's scope. Even if the adjacent code is obviously improvable, expose it through the
NOTICED BUT NOT TOUCHINGpattern in Scope Discipline; do not silently expand the slice. Scope creep within a slice simultaneously breaks the Rollback-Friendly contract (delete-and-replace within the same commit is hard to revert) and the Parallel Dispatch Iron Law (if one slice modifies files outside its declared scope, it may collide with a parallel slice).
Anti-patterns
- ❌ Starting implementation without checking the size (Step 1) -> this over-slices simple work, or under-slices L-sized features
- ❌ Forcing parallel dispatch on tasks with cascading edits -> violates the Iron Law
- ❌ Choosing Horizontal sweep for "new feature" work -> sweep is for cross-cutting modifications, not for greenfield additions
- ❌ Slicing too small for the sake of more slices, trying to parallelize -> the Step 3.4 size filter is not optional
- ❌ Skipping verify between slices for speed -> bugs compound; a bug in slice 1 makes slices 2-5 all wrong
- ❌ Mixing unrelated concerns into one commit -> see
git-workflow - ❌ "Cleaning up nearby code while at it" -> violates scope discipline (4.3)
- ❌ Dispatching a slice without an anti-hardcoding guard -> an isolated subagent may hardcode values or weaken tests just to turn green. The main Agent's dispatch prompt should carry: "implement the general logic; do not hardcode values or weaken tests; if a test looks wrong, surface it instead of patching around it"
- ❌ Trying to coordinate subagents during execution via shared state -> current CLI runtimes (Claude Code, Codex CLI, etc.) have no agent-to-agent channel; serialize through the main Agent, or merge into a single-writer slice
- ❌ Skipping the handoff block (Section 4.8) -> the next slice loses the audit trail (commands + exit codes), the issues-found list, and the procedure-compliance flag. A diff alone is not a handoff
- ❌ Writing the handoff before Verify passes -> the handoff records what passed, not what was attempted; handing off early hides failures behind a seemingly clean block
Relationship to Other Skills
- Upstream planning sources (any one): built-in Plan,
planning-with-files、spec-design, or a task given directly by the user; this skill does not depend on the source test-driven-development: manages the red→green cycle in Step 4.1test-designer: may produce the failing tests that this skill's green phase must satisfysystematic-debugging: run when the result of any slice breaks regressionverification-before-completion: the final gate after all slices are mergedgit-workflow(auriga-workflow plugin): the atomic commit rules referenced in 4.5