/tune

name: tune
description: >-
  Harness retro — turn recurring agent mistakes into one-line fixes. Mines
  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), `out/tune/principles.md` if present (promoted cross-cutting principles — a lens for judging new findings), 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. Name the class a cut falls into: **Conflict** (two layers pulling opposite ways — quote both sides), **Duplicate** (keep the copy nearest its point of use), **Obvious** (restates what the code or the model's defaults already show), **Judgement-now** (a blanket worst-case rule a current model calls better from context), or the vanished incident class above — first match in that order wins. A line that fits none is a **Gotcha** — load-bearing; it survives this run.

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**, where it goes, and the **one-line principle** the finding generalizes to: the transferable "why" that would prevent the whole incident class, not just this instance. 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.

**Prove the rules bite** — for the mechanical rungs (allowlist, script, hook), applying isn't done: with the change in place, inject the exact violation it exists to catch, observe the block or failure, revert the injection, observe green again