config-audit/docs/delete-and-rebuild-brief.md

# Brief — Delete-and-Rebuild (config subtraction)

**Status:** BRIEF, not a plan. No code, no chunk breakdown, no version number committed.
Written 2026-07-29 so a session starting Thursday evening has a durable starting point.
STATE.md is gitignored in this repo, so this file — not STATE — is the record.

---

## 1. Trigger and its provenance

The operator relayed a third-party YouTube summary (Hyper Automation Labs) of a talk
Boris Cherny reportedly gave at Y Combinator Startup School, one day after Opus 5
shipped. Claims attributed to him in that summary:

- Anthropic deleted ~80 % of Claude Code's own system prompt when Opus 5 landed.
- Advice to users: every six months, delete your CLAUDE.md, your skills, your hooks —
  see what the model does.
- Rebuild method: delete everything, use it, add one line back only when the model
  stumbles on the same thing repeatedly.
- The model measured *slightly more intelligent* with the built-in prompts stripped.

**None of this is verified.** It is a secondhand transcript of a talk, from a channel
selling a lead-magnet PDF. It is recorded here as the *trigger*, and it is deliberately
not load-bearing for anything below. This repo already has one scar from treating a
plausible quote as fact («Fable low ≈ Opus high», fabricated, rejected 2026-07-14).

If the attribution ever needs to matter — e.g. if this becomes a `BP-*` entry in the
best-practices register — it needs a primary source (the YC talk itself, or an
Anthropic doc), and until then the register's source field must read
*"third-party video summary, unverified"*. Verification is a Thursday task, not a
prerequisite: the feature justifies itself from this repo's own logic (§3).

## 2. Verified ground truth (checked against the local CLI, 2026-07-29)

These *are* facts, and they are what make an empirical variant buildable:

| Fact | How verified |
|---|---|
| `claude --bare` exists — "Minimal mode: skip hooks, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, and CLAUDE.md auto-discovery. Sets `CLAUDE_CODE_SIMPLE=1`." | `claude --help` |
| `claude --system-prompt <prompt>` — replaces the session system prompt | `claude --help` |
| `--append-system-prompt`, `--add-dir`, `--setting-sources <user,project,local>`, `--plugin-dir`, `--settings`, `--agents` — all present and all usable to compose an isolated config for a controlled run | `claude --help` |

So the `CLAUDE_CODE_SIMPLE=1` env var the video calls "undocumented" is, in this CLI
version, a documented flag (`--bare`). That matters: an A/B ablation harness would not
need an undocumented hook.

## 3. Why this fits this repo (the argument that does *not* depend on §1)

The plugin has three pillars — Health, Opportunities, Action. Every existing command
answers a question on the **addition** axis:

- `feature-gap` — what could you add?
- `optimize` — what would fit a better mechanism?
- `posture` / `tokens` / `manifest` — how good/expensive is what you have?
- `fix` / `implement` — apply changes.

**Nothing answers the subtraction question: what is no longer earning its rent?**
`feature-gap` has no inverse. That is a real hole, independent of who said what on
a stage.

Two further reasons this belongs *here* specifically:

1. **Nothing in the repo measures instruction age.** Verified by grep over `scanners/`:
   `stale` appears only for knowledge-register entry age (`lib/knowledge-refresh.mjs`)
   and for stale plugin-cache versions (`scan-orchestrator.mjs`, M-BUG-11). No scanner
   touches `git blame`, `mtime`, or the vintage of a CLAUDE.md block. An instruction
   written for Sonnet 3.5 and an instruction written last week are indistinguishable to
   every current scanner.
2. **Deleting bravely is only sane if you can undo it.** That is already pillar three:
   `lib/backup.mjs`, `rollback-engine.mjs`, `auto-backup-config.mjs` (PreToolUse), and
   `drift`'s `saveBaseline` / `loadBaseline` / `diffEnvelopes`. The safety net exists;
   the feature that would use it does not. This is arguably the strongest framing:
   *config-audit is already the infrastructure that makes "delete it and see" a
   measurement rather than a gamble.*

## 4. Reusable machinery (do not rebuild these)

| Need | Already exists |
|---|---|
| Snapshot config before deleting | `scanners/lib/baseline.mjs` (`saveBaseline`), used by `drift` |
| Diff before/after | `diffEnvelopes` in the same module |
| Backup + restore individual files w/ sha256 manifest | `scanners/lib/backup.mjs`, `scanners/rollback-engine.mjs` |
| Cost of each source, always-loaded subtotal | `scanners/manifest.mjs`, `token-hotspots.mjs` |
| Human-approved-writes command pattern | `knowledge-refresh`, `campaign` (both non-byte-stable by design) |

## 5. Candidate shapes (sketches — pick on Thursday, do not pre-commit)

**A. Deterministic vintage scanner (`CA-VIN-*`).** Per instruction block in CLAUDE.md /
rules / skills / hooks: age from git history, plus a compensatory-phrasing signal
(blocks that exist to correct model behaviour — "ALWAYS", "never forget", "read the
whole file first", "don't guess"). Output: ranked deletion candidates with age + token
cost + why it looks compensatory. Cheapest, most testable, fits the existing scanner
architecture, and composes with `tokens`/`manifest` for the payoff figure.
*Caveat:* `~/.claude` is not git-tracked, so age there falls back to `mtime`, which is
weaker evidence. Project-level CLAUDE.md/rules get real git ages.

**B. Protocol command (`/config-audit rebuild`).** The delete → live with it → earned
re-add ledger loop, spanning sessions: archive current config, record what was archived,
and maintain a ledger where a line only returns when the operator records that the model
actually stumbled on it. Highest fidelity to the source idea; needs cross-session state
(the `sessions/` machinery already exists) and is inherently not byte-stable.

**C. Measured ablation harness.** Use `--bare` + `--system-prompt`/`--add-dir` to run the
same prompt with and without a block and compare. Closest to a real verifier, most
expensive in tokens, weakest determinism. Probably a later `--experimental` sub-mode of
A or B rather than its own command.

Likely landing: **A first** (deterministic, testable, immediately useful), with B as the
workflow that consumes A's output. C stays a documented idea until A+B exist.

## 6. Hard constraints (carry these into any implementation)

- **`~/.claude` is NOT git-tracked.** A literal `rm` there is unrecoverable. Archive by
  `mv` into `_archive/`, never delete. This is already an inviolable rule in STATE.md.
- **`settings.json` is pathguard-protected** — no Edit/Write. Use `jq` + temp file +
  atomic `mv`, with operator OK ([[settings-json-pathguard-write]]).
- **New scanner ⇒ the 7-step byte-stability checklist** ([[adding-scanner-byte-stability]]):
  scanner + orchestrator + scoring area-map + strip-added-scanner + humanizer count +
  SC-5 + humanizer wiring (`SCANNER_TO_CATEGORY` entry and `TRANSLATIONS.static` per RAW
  title — M-16/M-17). Frozen `tests/snapshots/v5.0.0/` must stay untouched.
- **TDD is inviolable** — red tests before implementation, including for .md contracts.
- **`feat:` commits require non-trivial diffs in both README.md and CLAUDE.md**
  ([[docs-gate-feat-requires-readme-claudemd]]).

## 7. Open questions for Thursday

1. Scope of the deletion candidate set: user-level `~/.claude` only, project only, or both?
   (Age evidence is much stronger for project-level, per §5A.)
2. Is "compensatory phrasing" detectable with acceptable precision, or does it need the
   agent layer (like `optimize`'s precision-gated `optimization-lens-agent`)?
3. Does this ship as its own command, or as a `--subtract` mode of `optimize`?
   Both are defensible; command count is already 21.
4. ~~Ordering against the existing queue.~~ **Decided 2026-07-29:** the operator
   prioritized this work ahead of pipeline step 4 (`rollback`), to start Thursday
   2026-07-30. Do not re-litigate. The open part is only what follows it — the
   prior order stands underneath: step 4 `rollback`, then the M-11→M-20 batch
   release, then the v5.13 plan.

## 8. Verifisering (testable criteria)

**Before building anything:**

- [ ] `grep -rniE 'blame|mtime|birthtime' scanners/` returns no instruction-age handling
      → confirms §3.1 still true at build time.
- [ ] `node scanners/drift-cli.mjs <path> --save --name pre-subtraction` succeeds and
      `lib/baseline.mjs` round-trips → confirms §4 reuse is real, not assumed.
- [ ] If any claim from §1 is to be written into the register: a primary source exists
      (URL to the talk or an Anthropic doc). Otherwise the entry is not written.
- [ ] **The age signal actually exists.** §5A's fallback claim — "project-level
      CLAUDE.md/rules get real git ages" — is untested. Run
      `git log --format=%ad --follow -- CLAUDE.md .claude/rules/` across two or three
      real repos. If most instruction blocks trace back to a single bulk commit, per-block
      age carries no information, shape A's primary signal collapses to the
      compensatory-phrasing heuristic alone, and §7.2 (agent layer) is answered for us.
      Check this *before* writing any scanner code.

**If shape A is built:**

- [ ] Red tests exist and fail before implementation.
- [ ] `node --test 'tests/**/*.test.mjs'` green, count strictly greater than 1365.
- [ ] `git diff --stat tests/snapshots/v5.0.0/` is empty (frozen baselines untouched).
- [ ] `node scanners/self-audit.mjs --check-readme` passes (badge counts updated:
      scanners 16 → 17).
- [ ] Every new finding renders with a non-`Other` `userImpactCategory` and a
      non-`_default` action language → humanizer wiring correct (M-16/M-17).
- [ ] Dogfood on this machine produces at least one candidate the operator agrees is
      genuinely dead weight, and zero candidates the operator judges load-bearing
      (precision over recall — a false "delete this" is far more costly than a miss).