findings-ledger
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
SKILL.md.claude/skills/findings-ledger/SKILL.md
GitHubFindings 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