# Code Review Plan Create

> Code Review Plan Create

- Skill: `darthmolen/code-review-plan-create` (Agent Skill)
- Install (CLI): `npx skillmds@latest add darthmolen/code-review-plan-create`
- Raw SKILL.md: https://api.skillmd.com/api/skills/darthmolen/code-review-plan-create/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: darthmolen (https://skillmd.com/u/darthmolen)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/darthmolen/code-review-plan-create

---

# Create a Code-Review Meta-Plan

First punch-in command of the code-review workflow. Produces the **meta-plan** that drives slicing — a single document at `planning/YYYY-MM-DD-code-review-plan-<slug>.md` (frontmatter `type: code-review-plan`) with a slice table that the rest of the workflow operates on.

**Core principle:** Git is the source of truth, plans are best-effort context. Commits land in three patterns — clean (matches a plan), revised (matches a post-receive plan version), drifted (matches no plan). This skill maps what it can and Q&As what it can't.

## When to Use

- After implementation work has landed on a branch and you're ready to review it.
- When you want to slice a long-running branch into reviewable chunks.
- When you have a branch with mixed plan-driven and ad-hoc work and need to surface boundaries.

## Process

### Step 1: Identify Branch and Base

Defaults: current branch, base = `origin/main`. Confirm both with the user before walking commits. Edge cases:
- Branch has no upstream → ask which base to use.
- Working tree dirty → warn but proceed; SHAs in the meta-plan are committed-only.
- Detached HEAD → bail, ask user to check out a branch.

### Step 2: Walk Commits

```bash
git log --oneline --reverse <base>..HEAD
git log --pretty=format:"%H%x09%ad%x09%s" --date=short --reverse <base>..HEAD
```

Capture for every commit:
- full SHA, short SHA
- author date (yyyy-mm-dd)
- subject line
- body (for plan-doc references / co-author info)
- file-touch summary (`git log --stat -1 <SHA>`)

### Step 3: Discover Candidate Plan Docs

Scan all of:
```
~/.claude/plans/*.md
~/.copilot/session-state/*/plan.md
<project>/planning/**/*.md
```

For each candidate, extract:
- frontmatter `type` (filter to `plan` or no type — skip `code-review-*` types here)
- frontmatter `slug` if present
- first H1 heading
- file mtime and creation date
- any explicit slug-style file basename

### Step 4: Map Commits → Plans

For each plan candidate, score commits by:

1. **Plan slug or filename in commit subject** — strong match.
2. **Plan filename referenced in commit body** — strong match.
3. **Plan H1 keywords overlapping commit subject** (≥3 non-trivial words) — medium match.
4. **Time-window heuristic**: commits authored within `[plan_creation_date, plan_creation_date + 14 days]` — weak match, used only when other signals tied.
5. **Commit subject prefix match** (e.g., commits prefixed `Phase B1.x:` map to a plan whose body or H1 mentions "Phase B").

A commit may match multiple plans; weakest match wins only if no stronger match exists. Threshold: at least one strong OR two medium matches required to claim a mapping.

### Step 5: Surface to User

Present a draft mapping in chat:

```
Commit mapping draft for <branch> (<base>..HEAD = N commits):

PLAN: <path/to/plan-A.md>
  Score: 23 commits matched (12 strong, 11 medium)
  - <SHA> Phase B1.a: dual-write swarm-phase ...
  - <SHA> Phase B1.b: ...
  ...

PLAN: <path/to/plan-B.md>
  Score: 8 commits matched (5 strong, 3 medium)
  - <SHA> Smart Continue: wire the leader's repair_plan_after_failure tool
  ...

UNMAPPED (12 commits):
  - <SHA> SPA: re-hydrate after recovery actions so SSE reconnects
  - <SHA> Randomize hung-swarm-7e1c8d95.sql by default
  ...
```

### Step 6: Q&A on Unmapped Chunks

For each unmapped chunk:
1. Show the commits with subjects and short SHAs.
2. Ask: "These commits aren't mapped to any plan. Are they:
   - one slice of related work, or
   - multiple slices, or
   - should they be folded into an adjacent mapped plan's slice?"
3. If "one/multiple slices", ask for a name and focus areas for each.
4. If "fold into adjacent", ask which plan and adjust the mapping.

### Step 7: Confirm Slicing

Show the user the proposed slice table:

```
Proposed slices:

| # | Name | Commits | Plan docs | Focus |
|---|---|---|---|---|
| 01 | state-machine-foundation | <base>..<sha> (15 commits) | plan-A.md | dual-write transitions, drop legacy columns |
| 02 | smart-continue            | <sha>..<sha>  (5 commits) | plan-B.md | leader repair tool wiring |
| 03 | recovery-recommendation  | <sha>..<sha>  (8 commits) | plan-C.md, plan-D.md | recommendation surface + orphan defense |
| 04 | demo-seeds-randomization | <sha>..HEAD   (3 commits) | (none — ad-hoc) | seed determinism, GUC pinning |
```

Iterate with user until they say "yes, write it." Allow:
- splitting a slice
- merging two slices
- reordering (must remain chronologically valid: each slice's `base_sha` is its predecessor's `head_sha`)
- renaming
- adjusting focus areas

### Step 8: Write the Meta-Plan

Filename: `planning/YYYY-MM-DD-code-review-plan-<slug>.md`. The `<slug>` is typically the branch name kebab-cased (`feature-state-machine` → `feature-state-machine`), or user-provided.

```markdown
---
type: code-review-plan
branch: <branch>
base_sha: <full SHA>
head_sha: <full SHA>
slug: <slug>
slice_count: <N>
created: YYYY-MM-DD
---

# Code Review Plan — <branch>

## Context

<2-4 paragraphs: what's on the branch, why it's being reviewed now,
known plans and their state (clean / revised / drifted), any constraints.>

## Slice Table

| # | Name | base_sha | head_sha | Plan docs | Focus areas |
|---|---|---|---|---|---|
| 01 | state-machine-foundation | abc1234 | def5678 | planning/<plan-A>.md | • dual-write transitions through IStateTransitionService<br>• drop legacy Phase/Status columns<br>• migration safety |
| 02 | ... | ... | ... | ... | ... |

## Slice Detail

### Slice 01 — state-machine-foundation

**Commits (15):**
```
<git log --oneline base..head for slice 01>
```

**Plan docs:**
- [<plan-A.md>](path/to/plan-A.md) — short context on what the plan covered

**Focus areas:**
- Verify all transitions go through IStateTransitionService (no direct entity writes).
- Confirm legacy column drops are accompanied by data backfill or migration safety net.
- ...

**Known context (optional):**
- Plan went through one round of review-receive; the v2 of the plan is what was implemented.
- Phase B1.k landed late and may show up at slice boundary.

### Slice 02 — ...
[same shape]

## Review Order

Default: 01 → 02 → ... → N. Adjust if some slices logically must precede others.

**When `slice_count > 1`, you MUST include a dependency table** instead of prose. Tables are scannable; prose dependency callouts get skimmed past. Example:

| Slice | Depends on | Why |
|---|---|---|
| 01 | (base) | foundation |
| 02 | 01 | builds on the state machine introduced in 01 |
| 03 | 01, 02 | fixes target paths introduced earlier |
| ... | ... | ... |

Every slice from 02 onward should have at least one dependency row — usually `(NN-1)` at minimum, with additional cross-slice deps called out where they exist (e.g., a UI slice depending on an event-broker slice). If a slice is genuinely independent of all others, put `(none)` and explain why.

## Stopping rules

- Pause after any slice that produces ≥3 Critical findings.
- Pause if `code-review-plan-execute` reports >2 failed slices.
- User may always interrupt and re-evaluate.

## Out of scope

- <if any: e.g. "we are not reviewing the docs commits 4a2469d / 1f80579 — they are documentation-only and listed but not sliced.">
```

### Step 9: Confirm and Notify

Report to chat:
- Path of the meta-plan
- Slice count
- Total commits covered
- Any commits intentionally excluded from slicing
- Suggested next step:
  - **If you want adversarial review of the slicing strategy:** run `plan-send-review` on the meta-plan.
  - **If you trust the slicing:** run `code-review-plan-execute` directly to seed and review.

## Heuristics That Help Discovery

- Look for `Phase X.y` or `[ticket-id]` prefixes — these are usually plan-owned.
- Co-author trailers (`Co-Authored-By:`) often correlate with plan-driven work.
- Commits with bodies referencing `planning/` paths are giveaways.
- Single-commit "Fix:" / "Chore:" entries are usually drift; group them by file/theme.

## Do Not

- Fabricate commits or SHAs.
- Map commits to plans the file system can't confirm.
- Write the meta-plan without user sign-off on the slice table.
- Force every commit into a slice — out-of-scope is fine if the user says so.
- Use a slug already in use elsewhere in `planning/` for `code-review-plan` files.

## Red Flags

| Thought | Reality |
|---|---|
| "Just put every commit in slice 01" | A 60-commit slice is unreviewable. Push back. |
| "I can guess the focus areas" | Ask. Wrong focus areas waste reviewer effort. |
| "The plan looks close enough" | Confirm with the user — close-enough mappings are how drift accumulates silently. |
| "Skip the Q&A — auto-cluster the unmapped" | The Q&A is the value. Auto-clustering is what created the mess. |