| 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:
- CLAUDE.md rule — for a two-strike mistake prose can prevent. One
line, imperative, specific.
- Permission allowlist entry — for a safe command prompted repeatedly.
- Script replacing prose — for a procedure the agent re-derives; a
deterministic script is cheaper and can't be misremembered.
- Hook — only for must-never-happen actions; prose cannot block, hooks
can.
- New-skill candidate — when a CLAUDE.md section has grown into a
procedure; sketch the skill, don't build it unbidden.
- 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.
