config-audit/commands/optimize.md

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

```bash
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.