tune · diff
git:20260714.f7ff09b to git:20260718.d8671ae
31 added, 8 removed. Audit A to A.
---
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) and `out/dev/bugfix-log.md` if present
- (recurring root causes are harness findings too).
+ 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.
## 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
+ (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`:
```markdown
- | Date | Finding | Proposal | Verdict | Provenance |
- |------|---------|----------|---------|------------|
- | 2026-07-06 | `cat` fails (bat alias), 4 sessions | rule: use Read tool, never cat | accepted | sessions 06-28→07-03 |
- | 2026-07-06 | user rejects auto-PR-body edits | (rejected — user prefers manual) | rejected | — |
+ | 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:
+
+ ```markdown
+ - 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.