tune · diff

git:20260710.355dbf7 to git:20260714.429242b

10 added, 13 removed. Audit A to A.

---

name: tune

description: >-

Harness retro — turn recurring agent mistakes into one-line fixes. Mines

- recent Claude Code session transcripts (plus the bugfix log and past tune

- runs) for repeated user corrections, permission-prompt friction, re-typed

- instructions, and rules that get violated anyway; cross-references the

- findings against the current CLAUDE.md, skills, and settings; and proposes

- ranked changes one at a time on an escalation ladder — a CLAUDE.md rule

- (only for a mistake made twice), a permission allowlist entry, a script

- replacing repeated prose, a new-skill candidate, or the deletion of a rule

- that no longer earns its context cost. Nothing is applied without explicit

- approval, and accepted/rejected findings persist in out/tune/learnings.md

- so future runs adapt. Use when the user says "/tune", "improve my setup",

- "why does claude keep doing X", "the agent keeps making the same mistake",

- or after a frustrating session. done's one-line retro catches one lesson

- at ship time; tune is the periodic audit of the whole harness.

+ recent session transcripts (plus the bugfix log and past runs) for

+ repeated corrections, permission friction, and rules that get violated

+ anyway, then proposes ranked changes one at a time: a CLAUDE.md rule, an

+ allowlist entry, a script replacing repeated prose, a new-skill

+ candidate, or a deletion that no longer earns its context cost. Nothing

+ applies without approval; accepted/rejected findings persist in

+ out/tune/learnings.md. Use when the user says "/tune", "improve my

+ setup", "why does claude keep doing X", or after a frustrating session.

+ done's one-line retro catches one lesson at ship time; tune is the

+ periodic audit of the whole harness.

---

# tune — the harness retro

`/tune` — audit the current project's harness against recent sessions

`/tune all` — widen across every project under `~/.claude/projects/`

Answer one question: **what keeps going wrong across sessions, and what

one-line change would make it impossible next time?** Correcting the agent

fixes one session; correcting the harness fixes every session after it.

The evidence is already on disk — the transcripts recorded every

correction, every retyped instruction, every permission prompt. This skill

reads them so the user doesn't repeat them.

## Step 0 — Scope, then inventory

**Scope:** default is the current project's transcripts — the last ~10

sessions or 2 weeks, whichever is smaller — from

`~/.claude/projects/<project-dir>/*.jsonl` (the dir name is the project

path with `/` → `-`). `/tune all` widens to every project; mining gets

shallower per project, say so.

**Inventory the harness first** — findings only mean something against the

baseline. Read: user + project `CLAUDE.md`, the installed skills (names +

descriptions), `settings.json` / `settings.local.json` (permissions,

hooks). Also read `out/tune/learnings.md` (past accepted/rejected — don't

re-propose what was rejected) and `out/dev/bugfix-log.md` if present

(recurring root causes are harness findings too).

## Step 1 — Mine the transcripts (cheap models, parallel)

Bulk transcript reading is a job for a **cheap model, not the frontier

one** — spawn the miners with `model: haiku`, one per evidence stream,

concurrently:

- **Corrections:** user messages that correct, redo, or undo the agent's

work — especially the same correction phrased across different sessions.

The strongest signal there is.

- **Friction:** permission prompts approved again and again, commands the

user retypes, tool errors hit repeatedly (a broken alias, a missing

binary, a path that's always wrong the first time).

- **Ignored rules:** places where a `CLAUDE.md` rule already exists and

the transcript shows it being violated anyway — prose that failed needs

a mechanism, not more prose.

- **Re-derived procedures:** multi-step sequences the agent works out from

scratch in session after session — candidates for a script or a skill.

- **Dead weight:** rules and skills that never once became relevant in the

mined window.

Each miner returns findings as: **what happened, quoted transcript lines,

session dates, occurrence count.** Full evidence goes to

`out/tune/.work/<stream>.md`; rank from the files, not the summaries.

## Step 2 — Cross-reference and rank

- **Two-strike rule:** a mistake made once is noise; twice is a pattern.

No proposal from a single occurrence — park it in learnings.md as

"watching" instead.

- **Check against the inventory:** if a rule already covers the finding

and was ignored, the proposal escalates to a stronger mechanism (script,

allowlist, hook) — never a second sentence saying the same thing.

- **Rank by cost:** occurrences × disruption. A correction retyped five

times outranks an elegant refactor of the rules file.

- **Deletions rank alongside additions.** A bloated CLAUDE.md degrades the

agent — every rule costs context in every session. A rule whose incident

class has disappeared is a finding.

## Step 3 — Propose, one at a time

Present findings **one at a time, highest impact first** — evidence

(quoted, dated), the proposed change as an **exact diff or text**, and

where it goes. The user approves, rejects, or edits each before the next

is shown. Apply only on an explicit yes.

The escalation ladder — always the *weakest mechanism that will actually

work*:

1. **CLAUDE.md rule** — for a two-strike mistake prose can prevent. One

line, imperative, specific.

2. **Permission allowlist entry** — for a safe command prompted repeatedly.

3. **Script replacing prose** — for a procedure the agent re-derives; a

deterministic script is cheaper and can't be misremembered.

4. **Hook** — only for must-never-happen actions; prose cannot block, hooks

can.

5. **New-skill candidate** — when a CLAUDE.md section has grown into a

procedure; sketch the skill, don't build it unbidden.

6. **Deletion** — of a rule, hook, or skill that no longer earns its cost.

After the session, update `out/tune/learnings.md`:

```markdown

|------|---------|----------|---------|------------|

```

The **Provenance** column is what makes rules retire-able: a future run

that sees the incident class gone can propose the deletion.

## Guardrails

- **Nothing applied without an explicit yes.** This skill edits the user's

configuration — the one place "just do it" is never acceptable.

- **Evidence or it isn't a finding.** Every proposal carries quoted

transcript lines with dates; "I noticed you often..." without a quote is

not presented.

- **Deletions as readily as additions.** A run that only ever adds rules is

doing it wrong.

- **Privacy is structural.** Transcripts stay local; quotes land only in

`out/tune/` files — ensure that path is gitignored (quotes come from the

user's private sessions) — and are never sent anywhere.

- **learnings.md stays under ~100 lines.** Prune resolved entries oldest

first; it's a steering file the next run reads, not an archive.

- **Respect the ladder.** Reaching for a hook when a rule would do adds

rigidity; adding a rule when a script would do adds context cost. The

weakest sufficient mechanism wins.