plan-simplifications

Plan Simplifications

Read the codebase under cwd (or a user-supplied path), understand it, and write a ranked simplification plan to ~/tmp/simplifications-YYYY-MM-DD-{slug}.md. The deliverable is a markdown doc the user can hand to /cook — this skill never edits the code being audited.

Process

1. Confirm scope — default is the entire repo at cwd. If the tree is large (>200 source files) or the user has hinted at a subset, ask one question: whole repo, a specific dir, or a file list. Skip vendored/build dirs (node_modules, .venv, dist, build, .git) regardless.

2. Read systematically — don't simplify what you don't understand. In order:

   • Top-level config: README.md, CLAUDE.md, pyproject.toml / package.json / Cargo.toml, build files.
   • Entry points: main, CLI commands, HTTP route registrations, exported package surface.
   • Module-by-module: prefer Explore subagent for breadth; read whole files for hot spots.
   • Tests — they document intended behavior and bound what "safe" means.

3. Build internal understanding — before listing candidates, be able to answer: what is this code for? What's the public contract? What are the hot paths? What's the test coverage shape? If you can't, keep reading.

4. Identify candidates — walk these categories explicitly. Each finding gets a file path with line numbers, an estimate of lines removed, and a risk note:

   • Dead code: unreferenced functions, classes, modules, imports, dependencies, exports.
   • Single-use abstractions: interfaces with one impl, factories producing one type, wrappers around one concrete call, generic helpers used once.
   • Duplication: near-identical functions, copy-pasted blocks, parallel hierarchies.
   • Stale code: commented-out blocks, feature-flagged-off branches with no live flag, deprecated paths with no callers.
   • Over-defensive code: validation/error handling for states the type system or upstream caller already prevents.
   • Backward-compat shims with no remaining callers (grep before trusting names).
   • Unnecessary indirection: one-line pass-through wrappers, layers that only forward.
   • Configuration knobs with one value across all environments.
   • Comments that restate the code or describe long-resolved historical context.

5. Rank — sort by impact (lines/abstractions removed, clarity gained) divided by risk (blast radius, test coverage at the site, whether behavior changes). High-impact-low-risk first.

6. Split safe vs behavior-changing — anything that touches a public signature, CLI flag, HTTP route, schema, or env var goes into the Behavior-changing section as opt-in, not the default bundle. Default bundle = strictly observable-behavior-preserving.

7. Write the artifact to ~/tmp/simplifications-YYYY-MM-DD-{slug}.md using the template below. Pick a slug from the repo name or focus area.

8. Tell the user the path and suggest the next step: /cook to turn the recommended bundle into an unattended plan, then /handoff to dispatch it. Do not invoke /cook yourself — the user reviews first.

Output template

---
written: YYYY-MM-DD by Claude Code
repo: {absolute path}
scope: {whole repo | path | file list}
commit: {git rev-parse HEAD}
---

# Codebase summary
{3–6 sentences: purpose, shape, entry points, test posture, anything unusual.}

# All candidates (ranked, highest impact-to-risk first)

## 1. {short title}  [impact: ~N LOC | risk: none/internal/observable]
**Where:** `{absolute path}:{line}` (+ other call sites)
**What:** {one sentence}
**Why it's safe:** {test coverage, no external callers, etc.}
**Steps:** {2–4 bullets the executor can follow}

## 2. ...

# Recommended bundle (this run)
- Candidates 1, 3, 5 — total ~N LOC removed, all internal-only.

# Behavior-changing (opt in explicitly via /cook)
## B1. {title}  [risk: observable — {what breaks}]
...

# Verification plan
- Run `{exact test command}` — must stay green.
- Spot-check: `{grep / build / smoke command}`.

# Do not touch
- {public API surfaces, files, contracts that are out of scope}

Anti-patterns

• Editing the code. This skill produces a plan only. If you find yourself reaching for Edit, stop — that's a job for the agent /cook hands off to.
• Candidates without line numbers. Every finding needs a path + line so the executor doesn't have to re-discover it.
• Suggesting refactors that aren't simplifications. Renaming, restructuring for taste, or adding abstraction is out of scope — only removal and collapse count.
• Trusting names over greps. "FooLegacy" might still be called. Verify with grep before claiming dead.
• Bundling behavior changes into the default set. Anything observable goes in the opt-in section; the default bundle must be safe to run unattended.
• Skipping the read phase. Listing candidates from filename patterns alone misses real wins and proposes unsafe ones.