/mine-history

name: mine-history
description: 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".

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

1. **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. 2. **Scope the window.** First run: full history. Later runs: since the last mining commit (find it with `git log --grep="history-mined" --oneline`). 3. **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. 4. **Tooling caution.** Count with `git rev-list --count`, never piped `wc` (output wrappers have silently truncated pipelines here). Write long listings to a scratch file and read that. Sanity-check any suspiciously round number. 5. **Output contract**, four sections, every bullet with hashes:

• A: ready-to-paste `domain-context.md` entries, 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 6. **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.ts` enforces the word budget, hash validity, and privacy rules). Commit message includes the phrase `history-mined` so 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.