hoa-repo-reckoning · git:20261119.25d141e · 2026-11-19 · sha256 9bc375a4ea42fb3a
hoa-repo-reckoning git:20261119.25d141eA
Immutable. This exact content never changes and is served at /api/v1/blob/9bc375a4ea42fb3a.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_wgsskaixuuiuhcbr/9bc375a4ea42fb3ab85edcf3a5791fdb5bcb072edfff6a74bda11d0e4ea8c3f5.json
Then /plugin install hoa-repo-reckoning@markdownregistry-wgsskaixuuiuhcbr in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: hoa-repo-reckoning description: >- Periodic deep audit of one whole repository's practices and machinery: parallel dimension reviewers, external research, adversarial verification, a ranked stop-doing list and unknown unknowns. Use when asked to deep-review or reckon a whole repo. Not for a diff or PR (ce-code-review), one repo's agent-session friction (ce-retro), or skill-catalog verdicts (suggest the user run hoa-skill-set-audit). disable-model-invocation: true metadata: revision: "1" areas: "software-development,work-management" targets: "runtime-agnostic" summary: "periodic deep audit of one whole repository: dimension finders, adversarial verifiers and a critic yield a ranked stop-doing list plus unknown unknowns" summary_zh: "定期深度审计单个仓库:分维度查找、对抗验证与补漏评审,产出排序的停止清单与未知的未知" kind: "entry" --- # hoa-repo-reckoning Settle what one repository costs its owner that nobody sees any more, plus what the owner does not know that would change the work. The output is two ranked tables, **A. dumb things still being done** and **B. unknown unknowns**, each finding verified by a context that did not produce it, and a follow-through on the previous reckoning. Explicit invocation only. It is expensive (a standard run fans out to about 20 workers) and it never edits the subject. ## Inputs - **Repository path** (required). Read its `AGENTS.md` / `CLAUDE.md` first; its rules beat the lens. - **Window** (optional). Default: since the last reckoning of this repo in the state dir, else 30 days. - **Depth** (optional): `quick`, `standard` (default), or `deep`, as defined in [the panel protocol](references/panel.md). A scheduled run passes `--depth quick`. ## Method Follow [the panel protocol](references/panel.md) end to end: run directory, scope, evidence basis, find, verify, critique, spot-check, report, gate. This skill supplies only the dimension roster. Pick dimensions using the panel's depth budget and justify each pick in `scope.md`. Briefs and starter commands are in [the dimension briefs](references/dimensions.md): 1. **history-forensics**: churn by top directory, fix-of-fix and revert chains, PR size, commits touching many files for a small change, direct pushes to the default branch. 2. **ceremony**: version, changelog and release gates; overlapping write-ups per increment; review rounds per PR. 3. **enforcement**: CI checks compared with server-side protection; gates that are advisory only. 4. **tests**: test/code ratio, tests of test infrastructure, coupling to private internals, OS matrix compared with OS-specific code. 5. **code-shape**: forks and copies by normalised-line overlap, single-caller wrappers, dead code, helpers longer than one screen. 6. **reach**: does what the repo produces reach its consumers (installs, deploys, docs versus reality)? 7. **boundary**: identity, secrets, corporate URLs in a public repo, generated files edited by hand. 8. **external** (one or two workers): unknown unknowns, with sources. 9. **agent-stack**, only for repos that are agents or harnesses: the layer table in the briefs. The critic always runs. When the subject is a skill library, skip catalog-level questions (necessity, overlap, listing budget); suggest the user run the explicit-only `hoa-skill-set-audit` for them. The model cannot invoke it. ## Output `report.md` in the run directory, generated by `uv run scripts/findings.py report RUN --prev <last run>`, with the parent's meta-diagnosis and suggested order written above the tables, followed by caveats (overlapping findings, what was not covered, `verification: single-context` if it applies). Also `ledger.jsonl`, which the next reckoning and `hoa-practice-retro` read. The chat reply is at most 10 lines: the header counts, the top three of each table, and the report path. Do not paste the tables into chat. ## Routing out Nothing is applied from inside the reckoning. After the owner decides an item (`uv run scripts/findings.py decide RUN ID accepted "<reason>"`), it goes to the owner's normal implementation flow; script or checker restructuring goes to `harness-engineering`; a finding whose `owner` is another repo is reported for that repo and never applied here. If a named route is not installed, the report names it and stops. ## Cadence Monthly for repos with active agent-driven work; after a burst (more than about 50 commits in a week, or a new subsystem); quarterly for quiet repos. Use `quick` between `standard` runs. Scheduling belongs to the operator (a scheduler that runs the agent headless with the skill and `--depth quick`); with no user present the run stops after the report and records no decisions. ## Provenance The bar (cause still on the tree, fix cheaper than the cost) and the decision ledger adapt Compound Engineering's `ce-retro`; recommendation follow-through adapts gstack `retro`; evidence-basis-first and budget posture adapt Waza `health`; slice budgets and the frozen baseline adapt ECC `brownfield-retrospective`. The method packages the owner's 2026-11-17 hoa deep review (9 finders, 9 verifiers, a critic and its verifier). Only if a script command fails (for example `uv` is not found), read [references/troubleshooting.md](references/troubleshooting.md).