zmNinjaNg: Skill for Claude Code

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.