Kjell Tore Guttormsen
7b3b487d26
The recall+precision halves of the CA-OPT hybrid motor for the three
mechanism-fit cases the deterministic OPT scanner (2a) deliberately skips:
lifecycle→hook (BP-MECH-001), unscoped path-specific→rule (BP-MECH-002),
absolute "never"→permission (BP-MECH-004).
New:
- scanners/lib/lens-prefilter.mjs — cheap, recall-oriented line scan of the
CLAUDE.md body; detector names mirror the register lensCheck fields; skips
fenced code, gates the path class on an instruction verb. Pure + 13 tests.
- scanners/optimize-lens-cli.mjs — discovery + OPT scanner + pre-filter; attaches
only the CONFIRMED register entry to each candidate (unverifiable → dropped,
Verifiseringsplikt); emits {deterministic, candidates, register, counts}.
- agents/optimization-lens-agent.md — opus precision gate (7th agent, orange):
reads the real CLAUDE.md, drops low-confidence candidates, keeps only genuine
opportunities, cites register id + source.
- commands/optimize.md — /config-audit optimize orchestrates pre-filter→agent→report.
Agent-driven → deliberately NOT byte-stable (own command, outside the snapshot
suite). No new orchestrated scanner → scanner count stays 15. Counts: agents
6→7, commands 18→19, suite 1055→1068. Self-audit A/A unchanged, readmeCheck
passed (clean HOME). Plan: docs/v5.7-optimization-lens-plan.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
123 lines
4.8 KiB
Markdown
123 lines
4.8 KiB
Markdown
---
|
|
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)
|
|
|
|
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).
|
|
|
|
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
|
|
node ${CLAUDE_PLUGIN_ROOT}/scanners/optimize-lens-cli.mjs <target-path> --output-file ~/.claude/config-audit/sessions/{session-id}/optimize-lens.json $GLOBAL_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`.
|
|
|
|
**Early exit:** if `counts.deterministic === 0` and `counts.candidates === 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.
|
|
- 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.
|