Tune

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//*.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. A config that doesn't fail on its violation is a no-op wearing a diff.

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

| Date | Finding | Proposal | Principle | Verdict | Provenance |
|------|---------|----------|-----------|---------|------------|
| 2026-07-06 | `cat` fails (bat alias), 4 sessions | rule: use Read tool, never cat | prefer harness tools over shell equivalents | accepted | sessions 06-28→07-03 |
| 2026-07-06 | user rejects auto-PR-body edits | (rejected — user prefers manual) | — | rejected | — |

The Provenance column is what makes rules retire-able: a future run that sees the incident class gone can propose the deletion.

Promote recurring principles. When two or more accepted rows — from this run or any earlier one — share a principle (the same idea, not necessarily the same words) that isn't already in out/tune/principles.md, propose adding it there: the two-strike rule applied one level up, with the same explicit-yes gate as every other change:

- Prefer harness tools over shell equivalents — findings 2026-07-06, 2026-07-14

One line per principle, each citing the findings that earned it. Future runs read the file in Step 0 and weigh new findings against it; sessions that author or rewrite skills and rules read it as a pre-write checklist. A principle retires only when its incident class has vanished — pruning its source rows from learnings.md is housekeeping, not evidence — and retire-ability applies one level up too. Keep the file under ~15 lines: a principles file too long to skim is a rules file wearing a new name.

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.