Planning and task breakdown

Planning + Task Breakdown

Adapted from addyosmani/agent-skills under the MIT License. Copyright (c) Addy Osmani. Plan-doc header template + bite-sized step granularity + file-structure-up-front section adapted from obra/superpowers/skills/writing-plans under MIT. Final review pass migrated to jutsu swarm doc-review (the Phase-2 universal QA gate).

A plan is the bridge between a spec and an implementation. The deliverable is a markdown file with vertical-slice tasks, each individually shippable.

When to invoke

• A spec exists (see spec-driven-development) and the user wants to start work
• The user says "what are the steps" / "how do we approach this" / "task list"
• A change spans >5 files or >500 LOC

Plan document header (every plan must start with this)

# <Feature Name> Implementation Plan

**Spec:** `docs/specs/<spec-file>.md`
**Goal:** <one sentence — what this builds>
**Architecture:** <2-3 sentences — approach + key invariants>
**Tech Stack:** <key libs / frameworks / files>

> **For implementers (human or agent):** execute this plan task-by-task with `subagent-driven-development` (recommended) or `executing-plans` (separate-session mode). Steps use checkbox (`- [ ]`) syntax for tracking.

---

The implementer needs to know WHY before HOW. The header is non-negotiable.

Process

Step 1: Read the spec

Locate the spec file (usually docs/specs/<latest>.md). If no spec exists, refuse — invoke spec-driven-development first.

Step 2: Map the file structure UPFRONT

Before defining slices, list every file the implementation will create or modify and the responsibility of each. Decomposition decisions get locked in here.

## File structure

- `cli/internal/findings/store.go` — SQLite handle + migration loader (NEW)
- `cli/internal/findings/migrations/0001_init.sql` — v1 schema (NEW)
- `cli/internal/findings/store_test.go` — Open / Close / migration idempotency (NEW)
- `cli/internal/cli/swarm.go` — post-FanOut hook (MODIFY ~line 484)

Rules:

• Each file = one clear responsibility
• Files that change together live together (split by responsibility, not by tech layer)
• In existing codebases, follow established patterns — don't unilaterally restructure
• If a file you'd modify has grown unwieldy, including a split in the plan is reasonable

Revision protocol. Files emerge during implementation. The structure section captures what's KNOWN at planning time, not a frozen contract. When a slice surfaces a new file, update this section in the same commit that introduces the file — the plan stays a current map, not a stale snapshot. The plan-doc is mutable through the implementation phase; only its acceptance criteria are immutable post-approval.

The implementer reads this and knows the surface area before reading any task.

Step 3: Decompose into vertical slices

Each slice:

• Touches every layer it needs (UI / API / DB / tests / docs)
• Is independently shippable, possibly behind a flag
• Has its own acceptance criteria
• Estimates at <500 LOC, <1 day, <5 files

3-7 slices is the sweet spot. Fewer = you're not slicing enough; more = the spec is too big.

Step 4: Map dependencies

Make the DAG explicit:

Slice 1: <describe> — depends on: nothing
Slice 2: <describe> — depends on: slice 1
Slice 3: <describe> — depends on: nothing  (parallel with 1+2)
...

Identify the critical path (longest chain). Any slices off the critical path can be assigned in parallel.

Step 5: Bite-sized steps inside each slice

Per-slice acceptance is necessary but not sufficient. Each slice ALSO carries a checklist of 2-5-minute steps the implementer (or a subagent in subagent-driven-development mode) executes in order. The implementer should never need to invent the next step.

### Slice N: <title>

**Files:**
- Create: `cli/internal/findings/store.go`
- Modify: `cli/internal/cli/swarm.go:484-492`
- Test:   `cli/internal/findings/store_test.go`

**Acceptance:**
- [ ] Open() creates DB at $HOME/.kaijutsu/findings.db with mode 0600
- [ ] Schema migration applies once; re-Open is a no-op
- [ ] Tests pass

**Steps:**
- [ ] Write the failing test for Open() / Close()
- [ ] Run: `go test ./internal/findings/` — confirm RED
- [ ] Implement minimal Store{} + Open() + Close()
- [ ] Run tests; confirm GREEN
- [ ] Add migration loader + 0001_init.sql
- [ ] Add re-open idempotency test
- [ ] Run tests; confirm GREEN
- [ ] Commit with message `feat(findings): Stage N — SQLite store`

Each step = one action. Target 2-5 min per step where the work decomposes cleanly. Some steps are inherently longer (designing a DB schema, writing a non-trivial migration, a hand-written algorithm) — that's fine; aim for atomicity-of-intent over wall-clock budget. The signal that a step is too big: if you can't articulate "step done = <observable thing>", split it. DRY / YAGNI / TDD / frequent commits are the bias. The implementer reads the steps top-to-bottom and never has to ask "what's next?"

Step 6: Write to disk

Save to docs/plans/YYYY-MM-DD-<short-slug>.md (or wherever the project's plan convention dictates).

Step 7: Multi-agent review (DO NOT skip)

Run the plan through doc-review — kaijutsu's universal QA gate that orchestrates claude / codex / antigravity in parallel with prose-tuned lenses:

jutsu swarm doc-review docs/plans/<filename>.md

(or via the skill wrapper: ~/.claude/skills/doc-review/scripts/run.sh docs/plans/<filename>.md)

Three lenses each surface different planning failure modes:

• claude (completeness) — missing dependencies between slices, hidden state assumptions, unfalsifiable acceptance criteria
• codex (implementability) — slices that are "actually two", vague success conditions, untestable steps
• antigravity (consistency) — drift from the parent spec, contradictions between slice acceptance and DAG order, missing references

Iterate findings:

1. Read the disagreement table FIRST. 1/N findings are conversation-starters worth investigating.
2. Fix issue-level findings + consensus minors.
3. Re-save the plan. Re-run jutsu swarm doc-review if substantive (or --replay <key> for free synthesis re-render after prompt-tuning).
4. Stop when the table shows zero issue-level findings or only contested-minor / info rows.

Step 8: Cost-tier classification

After doc-review converges, compose scope-check to classify each slice by reasoning space (plan / bead / code) per the cost-tier model. This is per-slice metadata for the implementer, not a review pass.

If jutsu swarm doc-review fails with "unknown preset", the doc-review skill isn't installed — jutsu install doc-review and retry. (doc-review is in this skill's deps.skills so a full jutsu install planning-and-task-breakdown should pull it transitively.)

Version constraint note: this skill's deps.skills pins doc-review@^0.1. When doc-review v0.2.0 ships, transitive installs of this skill won't pick it up automatically. If you need the newer version, install it explicitly with jutsu install doc-review@^0.2.

Anti-rationalization table

Excuse	Rebuttal
"I'll figure out the slices as I go"	Slices that emerge mid-implementation become accidentally non-shippable. Plan upfront.
"Acceptance criteria slow things down"	Acceptance criteria PREVENT slow things — they prevent the "done? not done?" debate at PR time.
"Dependencies are obvious"	They're obvious to the agent that wrote the plan. Future-you / collaborators read the DAG to parallelize.
"We'll skip the review"	Plans without review consistently produce slices that block on each other or balloon past 500 LOC. The review IS the deliverable.
"doc-review costs money / I'll skip it"	Bounded by --max-cost (default $1.00). The cost of catching a bad slice at plan time is 5–20× cheaper than catching it at PR time.

Hard rules

• The plan is the deliverable. Implementation happens in a separate session, after the user approves the plan.
• doc-review is non-negotiable. A plan that hasn't been multi-agent-reviewed is a draft.
• Save to disk. Conversation plans evaporate. File plans survive.
• No slice exceeds 500 LOC estimate. If it does, split.
• No "TBD" acceptance criteria. Every slice has concrete, observable success conditions before implementation begins.

Composes

• doc-review — universal multi-agent QA gate; prose-tuned lenses for the final review.
• scope-check — cost-tier classification per slice; flags creep risks. Runs AFTER doc-review converges, not as a review pass itself.

When NOT to use

• Single-file change where the diff IS the plan
• True experiment / prototype the user explicitly framed as throwaway