mine-history
Skill102 starsChanged 10 months agoApache-2.0View on GitHub
Use when asked to mine the commit history for lessons the agent instruction files have not captured, to audit whether domain-context and contracts reflect what actually broke, or to run the periodic learnings review. Triggers on "mine history", "audit learnings", "check domain context against history".
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- add-languageSkill
- fable-reviewSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Verify that the instruction system (AGENTS.md, AGENTS.project.md, agents/project/domain-context.md, playbooks) recorded the lessons the …
- Distinctive: line 23
After a busy stretch of fixes, or roughly monthly (see Cadence)
- Distinctive: line 24
After adopting this instruction system in a repo with existing history
- Distinctive: line 39
Ask what stable fact would have prevented the class.
- Distinctive: line 41
Should-not-have-happened: fixes that an existing contract or gate should have caught.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Commit History Miner
Overview
Verify that the instruction system (AGENTS.md, AGENTS.project.md,
agents/project/domain-context.md, playbooks) recorded the lessons the
repo actually paid for. The day-to-day self-improvement protocol captures
lessons one PR at a time; this skill is the periodic sweep that catches
what slipped through.
Core principle: every candidate carries commit-hash evidence. A lesson without a commit behind it is speculation, and speculation does not enter the instruction files.
When to Use
- "mine the history for lessons", "audit the agent files against history"
- After a busy stretch of fixes, or roughly monthly (see Cadence)
- After adopting this instruction system in a repo with existing history
Procedure
- Read what exists first. AGENTS.md, AGENTS.project.md, every file in
agents/project/. Only NEW lessons get reported; re-reporting a covered fact is noise that erodes trust in the sweep. - Scope the window. First run: full history. Later runs: since the
last mining commit (find it with
git log --grep="history-mined" --oneline). - Probe, in order of yield:
- Reverts:
git log --grep=revert -i --oneline. Each revert is a paid experiment; the lesson is what not to retry and what worked instead. - Fix chains: group
fix(<scope>):commits by scope; any scope with a disproportionate count is one misunderstanding surfacing repeatedly. Ask what stable fact would have prevented the class. - Churn files: rank files by fix-commit touches; read the fix bodies.
- Should-not-have-happened: fixes that an existing contract or gate should have caught. Post-gate violations mean the gate has a hole.
- Reverts:
- Tooling caution. Count with
git rev-list --count, never pipedwc(output wrappers have silently truncated pipelines here). Write long listings to a scratch file and read that. Sanity-check any suspiciously round number. - Output contract, four sections, every bullet with hashes:
- A: ready-to-paste
domain-context.mdentries, grouped by its existing section headers - B: contract or project-rule candidates (only for recurring classes; name the Owns/Path/Never/Gate you would write, with real paths)
- C: generic rule candidates (only stack-agnostic classes; expect zero most runs)
- D: checked-and-already-covered list, one line each, so the next run knows what was verified
- A: ready-to-paste
- Apply through the protocol. Additions land as a PR touching the
instruction files: domain entries verbatim, contracts with existing
gate paths, budget re-checked (
agents-contracts.test.tsenforces the word budget, hash validity, and privacy rules). Commit message includes the phrasehistory-minedso step 2 finds it next time.
Judging candidates
| Signal | Verdict |
| Reverted approach with a working alternative | Domain entry: what failed, what works, do-not-retry |
| 3+ fixes, one underlying misunderstanding | Domain entry stating the stable fact |
| Recurring class across many commits (dozens) | Contract candidate, not just an entry |
| Security-shaped fix (secrets, tokens, storage) | Contract Never-line candidate |
| One-off typo/logic fix, no reusable fact | Skip; not every fix is a lesson |
| Fix predates the rule that now covers it | Already handled; list in section D |
Cadence (optional, not mandated)
About once a month is enough; the per-PR protocol does the daily work.
To schedule instead of remembering: any scheduler that can run the CLI
works (claude -p "/mine-history" from cron or a calendar automation), or
create a Claude Code routine with the /schedule command ("run
/mine-history on the first of each month"). Running it manually after a
heavy fix period is just as valid.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

