Prune

bonsai:prune

The half nobody else builds. A harness that only grows gets worse at month six — every resident token spends a finite attention budget, so removal is as valuable as addition.

Default is report-only. --apply proposes removals through the normal review gate; it never deletes unilaterally.

Procedure

1. Delegate first. Invoke /doctor. It already trims derivable content from a checked-in CLAUDE.md, finds unused skills, MCP servers, and plugins, and flags slow hooks. Everything it covers is out of scope here — report what it found and move on.

2. Scan deterministically.

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/prune_scan.py --project . --plugin-root ${CLAUDE_PLUGIN_ROOT}
   

   Returns findings by category. Do not re-derive any of it by reading files yourself — that's the determinism boundary, and the scan is cheaper and exact.

3. Judge each finding. The scan finds candidates; you decide. This is the part that needs judgment:

   Finding	What to weigh
   stale — never exercised since creation	Genuinely dead, or just guarding something rare? A security constraint that never fires is working. Never prune enforced constraints on staleness alone
   orphan — inventory entry with no file, or artifact with no provenance	Orphans are usually safe to reconcile. An artifact with no provenance may be hand-written by a human — leave it, just report it
   unscoped — a rule with no paths: whose content clearly correlates with a path	Propose adding paths:. This is a fix, not a removal, and it's often the highest-value finding
   conflict — two artifacts giving contradictory guidance	Must be resolved. Conflicting instructions mean Claude picks arbitrarily. Ask the user which wins
   oversized — CLAUDE.md over 200 lines after /doctor	Propose path-scoped splits for what remains
   redundant — guidance a linter or formatter now enforces	Safe to remove; the tool is the artifact
   superseded — an artifact the codebase has moved past	Check git history before claiming this

   Show the measurement, not the verdict. The one thing bonsai knows that a human reading the file doesn't is whether the file was ever consulted, so every line about an artifact states it. Each stale finding carries days_loaded_in_window, window_days, and coverage, and load_tracking.evidence carries the same for artifacts that aren't stale.

   .claude/rules/graphql.md — loaded on 0 of the last 60 days (created 2026-04-02)
   .claude/rules/testing.md — loaded on 14 of the last 60 days; keep
   

   Two caveats are not optional, because a confident number from an inactive sensor is worse than no number:

   • load_tracking.active: false means nothing has been recorded yet at all. Say the staleness is measured from the creation date and the count proves nothing.
   • coverage: "partial" (skills) means only model invocations are counted. A skill the team invokes by typing /name shows zero. Never propose removing a skill on a zero count alone — ask.

   The unit is days-with-a-load, not invocations. Write "loaded on 3 of the last 60 days", never "loaded 3 times".

4. Demote rather than delete. Preferred order: scope it (add paths:) → move it (CLAUDE.md to a rule, rule to a skill) → archive it (out of context, retained on disk) → delete. Deletion is the last resort, and the artifact's eval case in .claude/bonsai/evals/ is retained either way.

5. Replay eval cases when it's cheap. If an artifact has an eval case and you can tell from the current codebase that the situation no longer arises, say so — that's the strongest evidence for demotion. Do not spawn model runs to replay cases in v1; automated replay isn't built yet, and pretending otherwise would be worse than admitting it.

6. Report the ledger. Always, even with nothing to prune:

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/footprint.py --plugin-root ${CLAUDE_PLUGIN_ROOT} --project . --format line
   

   One line for bonsai's own cost, one for the artifacts it maintains, one for what pruning would recover. This is the accountability surface for the whole tool — never skip it.

7. Route removals through review. With --apply, write each removal as a proposal to .claude/bonsai/proposals/ using the standard template, with the removal as the artifact content and the scan finding as the evidence. Then tell the user to run /bonsai:review. Same gate as additions: bonsai does not get to quietly delete a team's configuration.

Never

• Delete anything without approval, at any confidence.
• Prune an artifact a human wrote by hand without flagging it as human-authored first.
• Prune an enforced constraint (hook or permission) because it hasn't fired. Not firing is success.
• Touch CLAUDE.local.md or user-level config — those are personal, and not this repo's business.
• Report zero findings as a problem. A lean harness is the goal; finding nothing means it's working.