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

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