mine
Improve a skill, tool, CLI or hook from how it actually went in your past Claude Code and pi sessions. Findings are routed to /brainstorm, /grill-me or building them.
SKILL.mdskills/mine/SKILL.md
GitHubThis skill finds what to change in a target and why, from how it went in past sessions.
- The argument names a target: a skill, a pi extension or tool, a CLI, or a Claude Code hook or setting.
- With no argument, ask for a target. To review one session across everything it touched, use
/retro. - It writes no code unless the user picks findings to build at the end.
- It writes exactly one file, the findings file (see The file), and ends with a chat summary.
The reader
python3 <skill-dir>/scripts/sessions.py(substitute this skill directory's absolute path) reads Claude Code, its work profile and pi transcripts, read-only.--helplists its subcommands and flags, run windows and answer classes.- Each call scans every session, so it takes seconds to a minute.
Privacy
- Transcripts are private. Never write condensed transcript text to disk.
- Never quote a secret, and quote a phrase rather than a passage.
- Runs marked work profile, and memories under
~/.claude-work/, are paraphrased, never quoted. - Every subagent brief repeats these rules.
The target
Turn the target into matchers for runs, using the recipe for its kind. Before judging a specific system, read the docs page the repo's agent instructions point to for it.
- Skill:
--skill <name>.- A run ends at the prompt that invokes another skill, so it often includes work done after the skill's own part. Its error and denial counts are therefore pointers, not verdicts.
viasays whether you asked for the skill or the model reached for it.- The
bodypath shows which copy ran: the repo's deployed skill, an account-synced copy, or a plugin's. veris the commit that introduced that body text in the repo given by--repo(default: the cwd's);~marks a near match.
- Question-asking skill: the header splits answers into recommended, other (another option beat the recommendation), no-rec, custom and multi. Read the overall rates first. Per question header, only when headers recur:
- A header almost always answered with the recommendation is a decision the skill should state rather than ask.
- One often answered custom is missing an option.
- One where another option often wins has a wrong recommendation.
- pi extension or tool:
- Read the extension's source for the tool names it registers, and pass one
--toolper name. - Calls made from inside
codemodecount. - The header reports how many pi sessions offered the tool and how many called it. Offered but never called is a description or existence problem.
- Read the extension's source for the tool names it registers, and pass one
- CLI:
--cmd <binary>, plus--toolfor any harness tool that wraps it (find it in the repo).--helpcalls and an error followed by a retry are discoverability signals. - Hook or setting:
--text <regex>on its distinctive output, such as its block message or script name.- The header counts denials by kind, for Claude Code only. In pi, read the matched calls' results.
- A blocked call followed by a rephrased retry of the same intent is likely a false positive.
- The same denial repeating suggests a missing allow rule.
The file
- The findings file is
findings/<target>.mdin the agent notes of the project the target belongs to. - The user's instructions say where agent notes live and what a project is. Without them, the notes are
.agents/notes/in the repo and the project is the repo; write a.gitignorecontaining*there first. - Apart from that
.gitignore, the findings file is the only file a run writes. Subagents return their notes in their reply and write no files. - Never commit it.
- If it exists, this is a rerun. Read it first, pass
--since <its date>so only newer runs are read, and update the counts of the findings already there.
Gather
runs <matchers>gives the signal header and one line per run. Read the header before any run.- Run
work --path <target's paths> [--mention <name>]. It returns your typed turns from the ~10 most recent sessions that edited or discussed the target.- These record what was decided and why, and the complaints you stated.
- They are context, not constraints. A finding may go against one only when that improves the end result, and then it says so with
Reverses:.
- Feedback memories that mention the target are corrections someone already wrote down. Look in Claude Code's
projects/*/memory/and pi's memory store. - Read the target's own source and docs.
git logon the target's paths gives the date of its latest change.
Read the runs
- Read at most 40 runs: the most recent, keeping at least a few from each version seen. Say how many you left unread.
- With about 8 runs or fewer, read them inline with
runs <matchers> --show all. - With more, first print one line naming how many subagents you are about to start. Then hand batches of about 8 to fresh subagents on a cheaper model than yours:
model: "sonnet"in Claude Code, while pi's subagent roles already lock a cheap one. - Give each subagent:
- the target and a few lines on what it is meant to do;
- its run ids;
- the reader command to run itself (
runs <matchers> --show <id>,<id>).--showstops at 150 lines per run;--max-linesraises it when a run is cut before the target's part ends; - the privacy rules above.
- Never paste transcript text into a brief.
- For every run, the subagent returns:
- First failure: the first point where the run went worse than it should have, in one line, with its turn number (
#n); or "clean". - Next: what the user did once the target's part was done, which is often well before the run's
[ended]line. - Not the target's fault: harness or environment problems the run hit.
- First failure: the first point where the run went worse than it should have, in one line, with its turn number (
- In an interview skill, "yes", "no" and letters are answers, not corrections. A correction is the user redirecting, repeating themselves, rejecting the approach, or interrupting.
Label with the user
- Group the first failures into named categories.
- Ask one question round, using the harness's question tool when every question is a short pick (pi
ask_user_question, ClaudeAskUserQuestion). Ask about:- the runs whose note you are unsure of, each with its note and a one-line paraphrase of the moment;
- the category names, and any merges you propose.
- Fold the answers in before writing.
Findings
For each category:
Evidence: how many runs it hit out of all of them, the session ids, and a short quote or paraphrase. When every run behind it predates the target's latest change, mark it "possibly fixed".
Layer: where the fix belongs.
- the target's own text or scripts;
- the harness or an extension, through the harness's own extension points rather than patches to its built-ins;
- agent instructions or memory;
- the environment.
A cause shared with other targets is never a fix to this one.
Fix: what to change, a Size of S, M or L, and a Next:
/brainstormwhen the approach is open,/grill-mewhen it holds decisions, or build.
Two more kinds of finding come from the data, not from failures:
- Desire paths: a follow-up most runs share becomes a step the target offers itself. A tool-call sequence the agent works out again in most runs becomes a bundled script.
- Signal findings: what the header's numbers say on their own, such as the readings under Question-asking skill or a tool that is offered but never called.
A failure seen in one run is an anecdote, not a finding. Rank findings by the runs affected and what each failure cost: corrections, interrupts, abandoned runs.
Write
Write the findings file. On a rerun, edit it in place.
# Findings: <target>
<date> · <N runs (by source), M sessions, date range> · versions seen: <…> · latest change: <sha date>
## Findings
### 1. <category>
<What goes wrong, in 1–3 sentences.>
- Evidence: <k of N runs>; <session ids>; <quote or paraphrase>
- Layer: <layer> · Fix: <the change>
- Size: S · Next: build · Reverses: <decision, date> (only when it does)
- Status: <blank, or picked and where it went>
## Desire paths
- <what follows the runs, or what the agent keeps working out>: <k of N> → <exit or script>
## Anecdotes
- <one-off>: <session id>
## Rejected
- <title>: <one-line reason>
Then end with a chat summary holding only:
- the findings file's path;
- the counts ("5 findings from 34 runs");
- one line per finding (
1. <category> · <k/N> · <S|M|L> · <build|/grill-me|/brainstorm>), with the route last; - last, the top pick, in a sentence.
Pick
The user replies by number or in free text.
- Merge, refine or question: answer, and update the findings file when a finding's content changes.
- Build ("do 1, 3"):
- If a picked finding's Next is
/brainstormor/grill-me, ask once whether to build it anyway or route it first. - Then build them in this session one at a time, run the repo's checks, and mark each one done in the findings file.
- If a picked finding's Next is
- Any other pick: restate the finding as a seed (what, evidence, fix) and name its next command. Mark it picked in the findings file.