findings-ledger
Skill17 starsChanged 24 days agoMITView on GitHub
Use when recording, tallying, or triaging stochastic review findings — the append-only JSONL ledger where Tier 2 (advisory, unevidenced) reviewer output goes instead of blocking language. Triggers on "log this finding", "ledger add", "tally the findings", "triage findings", "is this finding recurring", "retire this noise", or whenever a reviewer produces an unevidenced concern that should be measured for recurrence rather than chased. For the review itself see code-review-and-quality or skill-library-review; for verifying formal claims with deterministic evidence see adversarial-claims-reviewer.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- Tsurai7/agentic-playbooktheir own version, first seen Oct 20, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- Tsurai7/agentic-playbook★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository38 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adversarial-claims-reviewerSkill
- autoresearchSkill
- browser-testing-with-devtoolsSkill
- codebase-cost-estimatorSkill
- code-review-and-qualitySkill
- content-opsSkill
- content-pipelineSkill
- conversion-opsSkill
- data-model-documentationSkill
- data-model-verificationSkill
- deployment-pipelinesSkill
- game-balancerSkill
- game-systems-designerSkill
- godot-engineerSkill
- growth-engineSkill
- iap-managerSkill
- library-investigatorSkill
- marketing-shaperSkill
- memory-extractionSkill
- outbound-engineSkill
- phaser-engineerSkill
- planning-and-task-breakdownSkill
- prompt-shaperSkill
- release-managerSkill
- revenue-intelligenceSkill
- rust-engineerSkill
- security-engineeringSkill
- securitySkill
- seo-opsSkill
- session-stateSkill
- skill-library-reviewSkill
- telemetrySkill
- typescript-analyticsSkill
- typescript-data-engineeringSkill
- typescript-testing-backendSkill
- typescript-testing-frontendSkill
- web3-smart-contract-engineeringSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
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 59
All via scripts/ledger.py (python3, stdlib only.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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
Findings Ledger
Stochastic judgment proposes; deterministic verification disposes (tier
doctrine: review-tiers — .claude/rules/review-tiers.md). This skill is the proposes side's
inbox: a single append-only JSONL at .claude/ledger/findings.jsonl where
Tier 2 findings accumulate fingerprinted, so the same defect reported twice
across runs collides to one entry — deterministically when the reviewer passes
a --category, heuristically on claim wording when it doesn't — and
recurrence across independent runs — not rhetoric — decides what gets
investigated.
The ledger file
- Location:
.claude/ledger/findings.jsonl, one JSON event per line. - Append-only. Status transitions are new events for the same fingerprint; prior lines are never mutated. Current status = the fingerprint's most recent event.
- Gitignored by default (machine-local noise). Team-shared mode, two
options: (a) commit
ledger.py export --out <path>output — one line per fingerprint with category, file, count and first/last seen, no claim text — to any tracked path outside.claude/ledger/; no.gitignorechange needed.fileandsymbolare still reviewer-supplied free text and get committed, so review the export before pushing. (b) Commit the raw ledger: in.gitignore, replace the.claude/ledger/line with.claude/ledger/*.lock(the lock sidecar stays local). Append-only + stable ordering keeps either diff reviewable. - CI runners don't persist it. Appends made during a CI job vanish with the runner — and CI must never push the ledger back to the repo. Upload the run's findings as a build artifact and harvest locally instead; patterns in references/ledger-format.md.
Entry fields: fingerprint, fingerprint_scheme (1 = text, 2 = structured;
absent on pre-#279 entries, read as 1), category and symbol (or null),
file, claim, tier, source, run_id, date, evidence (path or
null), status (NEW | RECURRING | INVESTIGATING | PROMOTED | RETIRED-NOISE).
Full schema, lifecycle, and fingerprint-normalization limits:
references/ledger-format.md.
Commands
All via scripts/ledger.py (python3, stdlib only; exit 0 = ok, 2 = setup/usage error; output ordering is deterministic). Resolve the script path first — references/install-paths.md:
PROJ="${CLAUDE_PROJECT_DIR:-.}"
# 1. Repo checkout
LEDGER="$PROJ/.claude/skills/findings-ledger/scripts/ledger.py"
# 2. Project Codex install
[ -f "$LEDGER" ] || LEDGER="$PROJ/.agents/skills/findings-ledger/scripts/ledger.py"
# 3. Global Claude Code install
[ -f "$LEDGER" ] || LEDGER="$HOME/.claude/skills/findings-ledger/scripts/ledger.py"
# 4. Global Codex install
[ -f "$LEDGER" ] || LEDGER="$HOME/.agents/skills/findings-ledger/scripts/ledger.py"
python3 "$LEDGER" add \
--file <path> --claim "<one sentence>" --tier 2 \
--source <agent-name> --run-id <id> [--evidence <path>] \
[--category <[ns/]kebab-slug> [--symbol <function|heading|key>]]
python3 "$LEDGER" tally
python3 "$LEDGER" triage [--threshold 2] [--age-days 14]
python3 "$LEDGER" promote <fingerprint> [--status INVESTIGATING] [--evidence <path>]
python3 "$LEDGER" retire <fingerprint>
python3 "$LEDGER" export --out <path>addcomputes the fingerprint (see Categories below) and labels a sightingRECURRINGonly when an earlier sighting came from a different--run-id; a repeat within the same run staysNEW. A--tier 1finding without--evidenceis demoted to tier 2 automatically — the tier rule, enforced. Control characters (newline, tab, …) in--file,--categoryor--symbolare rejected.- Recurrence counts distinct run ids, not raw sightings — an agent repeating itself within one run cannot cross the threshold alone.
triagelists fingerprints at/over the recurrence threshold as promotion candidates, and still-NEWsingle-run findings older than the age cutoff as retire-as-noise candidates. The/triage-findingscommand (repo-local maintainer tooling; not shipped by the installer) wraps this and proposes a ratchet target per candidate; the human disposes.promoterefuses to recordPROMOTEDwithout--evidence— a promotion is its encoded check.exportwrites the deduplicated per-fingerprint summary (sorted, byte-deterministic JSONL) to--out, and refuses any--outinside the ledger's directory.
Categories (structured fingerprints)
Two reviewers rarely phrase one defect the same way, so text fingerprints
rarely recur. Pass --category and the fingerprint becomes
sha256("v2" + normalized file path + category + symbol) — claim wording no
longer matters, and paraphrases collide.
--category— a short kebab-case slug naming the defect class, optionally under one namespace (slop/unused-dep). Lowercased; anything that isn't[ns/]slugwith each part[a-z0-9]+(-[a-z0-9]+)*is rejected. Seed vocabulary — prefer these, coin a new slug when none fits:Slug Use for fail-openerror/missing input path that grants or proceeds instead of denying missing-validationuser input reaches a sink unchecked missing-ci-wiringa test/check exists but CI never runs it missing-testbehavior change with no test exercising it stale-docdocs contradict the current code broken-referencelink, path or cross-reference that does not resolve vague-routingskill/agent description too unspecific to route on dead-codeunreachable or unused code/config secret-exposurecredential or token logged, committed or leaked Reviewer vocabulary (
slop/*,security/*, used by code-reviewer and security-reviewer): references/ledger-format.md.--symbol(optional, requires--category) — the function, heading, or config key the finding is about. Backticks and a trailing()are stripped, so`check_token()`,`check_token`(),check_token ()andcheck_tokenmatch. Omit it for file-level findings.- Without
--category,adduses the legacy text fingerprint (scheme 1), unchanged — existing entries keep their identity. A scheme 1 and a scheme 2 sighting of the same defect get different fingerprints, so stick to one scheme per defect.
Reviewers should pass both whenever the finding names a defect class and a location, reusing the same slug for the same class across runs:
python3 "$LEDGER" add --file src/auth.py --tier 2 --source code-reviewer \
--run-id pr-281 --category fail-open --symbol check_token \
--claim "check_token returns True when the verifier raises"The ratchet
A recurring fingerprint is a candidate to leave the stochastic layer forever:
investigate → encode as a scripts/validate.sh rule (Tier 0) or an
exit-nonzero evidence script (Tier 1) → promote with the encoded check as
--evidence → no LLM ever re-litigates it. Singles nobody re-reports get
retired. The ratchet only turns toward lower variance.
Related skills
- code-review-and-quality — produces the findings this ledger stores
- skill-library-review — library-audit findings route here when unevidenced
- adversarial-claims-reviewer — the Tier 1 pattern: evidence artifacts instead of ledger entries
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.

