config-audit/commands/optimize.md

name	description	argument-hint	allowed-tools	model
config-audit:optimize	Optimization lens — config that works but would fit a better mechanism (procedure→skill, lifecycle→hook, path→rule, never→permission)	[path]	Read, Write, Glob, Grep, Bash, Agent	opus

Config-Audit: Optimization Lens

The "is the config optimal?" axis (vs. the health scanners' "is it correct?"). It finds configuration that works but uses a mechanism a better one would fit — and frames every one as a Missed opportunity, never a mistake.

Mechanism-fit rules come from the provenance-stamped best-practices register (knowledge/best-practices.json); only CONFIRMED rules are surfaced. The motor is hybrid: a cheap deterministic pre-filter finds candidates, then the opus optimization-lens-agent judges each in context (precision-gated).

What the user gets

• Procedures → skills (deterministic, CA-OPT-001)
• Lifecycle phrasing → hooks (BP-MECH-001)
• Unscoped path-specific instructions → path-scoped rules (BP-MECH-002)
• Absolute "never" prohibitions → permissions / hooks (BP-MECH-004)
• --subtract: instructions that no longer earn their always-loaded rent (BP-SUB-001)

Each finding cites its register rule + source URL. A clean CLAUDE.md returns "no opportunities" — that is a good result, not a failure.

Implementation

Step 1: Determine target

Split $ARGUMENTS into a path (first non-flag argument; default: current working directory) and flags. Recognized flags: --global (include the user ~/.claude cascade in discovery) and --subtract (add the subtraction axis, below).

--subtract — the inverse question. Every other lens asks what to add or move; this one asks what no longer earns its always-loaded rent. It is opt-in because it asks something different, and because deleting is not undoable by reading. Pair it with --global to reach the user-level CLAUDE.md, where the always-loaded cost actually sits (it loads in every repo, every session).

If --subtract is present, say so up front:

Also running the subtraction axis — instructions that cost tokens every turn
without telling me anything I couldn't work out. Load-bearing local facts
(remotes, versions, paths, policy) are excluded before anything is judged.

Tell the user:

## Optimization Lens

Looking for configuration that works but would fit a better Claude Code mechanism...

Step 2: Run the lens CLI

Generate a session ID (YYYYMMDD_HHmmss) if no active session exists.

mkdir -p ~/.claude/config-audit/sessions/{session-id} 2>/dev/null
GLOBAL_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--global"; then GLOBAL_FLAG="--global"; fi
SUBTRACT_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--subtract"; then SUBTRACT_FLAG="--subtract"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/optimize-lens-cli.mjs <target-path> --output-file ~/.claude/config-audit/sessions/{session-id}/optimize-lens.json $GLOBAL_FLAG $SUBTRACT_FLAG 2>/dev/null; echo $?

Exit code 0 is normal. Only exit code 3 is a real error → "The lens couldn't run. Check that the path exists and contains a CLAUDE.md."

Step 3: Read the payload

Read ~/.claude/config-audit/sessions/{session-id}/optimize-lens.json with the Read tool. It has deterministic (already-confirmed OPT findings), candidates (pre-filter candidates with register provenance), register, and counts.

Under --subtract it also has a subtract block (candidates, register) and counts.subtractCandidates. Each subtraction candidate spans line–endLine (a whole block). Include the whole subtract block when spawning the agent.

Early exit: if counts.deterministic === 0 and counts.candidates === 0 (and, under --subtract, counts.subtractCandidates === 0), skip the agent and tell the user plainly:

✓ No mechanism-fit opportunities found.

Your CLAUDE.md holds facts, not procedures/automation/prohibitions that would be
better as skills, hooks, rules, or permissions. Nothing to change here.

Then go to Step 5.

Step 4: Spawn the precision gate

Tell the user what's happening and set expectations:

Found {counts.candidates} candidate line(s) + {counts.deterministic} deterministic finding(s).
Asking the optimization-lens agent to judge each in context (~20-40 seconds)...

Spawn the optimization-lens-agent (Agent tool) with:

• the full payload from Step 3 (deterministic + candidates + register),
• the session directory path so it can write optimization-lens-report.md.

The agent reads the actual CLAUDE.md, drops low-confidence candidates, and keeps only genuine opportunities — each citing its register rule + source.

Step 5: Present results

Read the agent's optimization-lens-report.md and present it formatted (markdown tables / grouped sections). Follow the UX rules: never show raw JSON or scanner progress; lead with a one-sentence summary of what was found before the detail. Make clear these are LOW-severity opportunities.

If the agent kept nothing from the candidates (all dropped) but there were deterministic findings, show those; if it kept nothing at all, show the clean result from Step 3.

Step 6: Next steps

End with context-sensitive next steps, explaining WHY each is useful:

• /config-audit plan — turn the kept opportunities into an action plan with backups before you change anything.
• /config-audit feature-gap — the complementary lens: features you don't use yet (this command is about mechanisms you do use that could fit better).
• Re-run /config-audit optimize anytime after editing CLAUDE.md.

Notes

• This command is agent-driven and not byte-stable — its output is a human-facing report, deliberately outside the deterministic snapshot suite.
• --subtract proposes, never writes. Nothing is deleted; act on a finding via /config-audit plan → /config-audit implement (backup + rollback).
• The subtraction floor is deterministic and runs before the agent, so a load-bearing block is never a candidate. It errs toward keeping: on a well-maintained config this axis is mostly a no-op, and that is a good result.
• The deterministic half (CA-OPT-001) also rides in the normal orchestrated audit; this command adds the prose-judgment half on top.
• No files are modified. To act on a finding, use /config-audit plan → /config-audit implement (backup + rollback) or edit by hand.