agentleFS
ZoneMinderZoneMinder/zmNinjaNg/.claude/skills/mine-history/SKILL.md

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".

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
  1. Very specific:

    Verify that the instruction system (AGENTS.md, AGENTS.project.md, agents/project/domain-context.md, playbooks) recorded the lessons the …

    line 10
  2. Distinctive:

    After a busy stretch of fixes, or roughly monthly (see Cadence)

    line 23
  3. Distinctive:

    After adopting this instruction system in a repo with existing history

    line 24
  4. Distinctive:

    Ask what stable fact would have prevented the class.

    line 39
  5. Distinctive:

    Should-not-have-happened: fixes that an existing contract or gate should have caught.

    line 41

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

SignalVerdict
Reverted approach with a working alternativeDomain entry: what failed, what works, do-not-retry
3+ fixes, one underlying misunderstandingDomain 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 factSkip; not every fix is a lesson
Fix predates the rule that now covers itAlready 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.