breed Repo Audit
Score a repository against the ten tips that separate a technically good repo from a product people can actually use and contribute to.
Core premise: technical excellence ≠ project excellence. This audit measures the second one only. It says nothing about whether the code is good.
Workflow
- Establish the target. Default to the cwd. If the user names another path or a GitHub URL, use that. Confirm you are at the repo root (look for
.git/). - Detect the ecosystem. Read
references/ecosystems.mdand identify the language/build stack. Every check below has an ecosystem-specific form — apply the right one. Multi-language repos: audit the primary published artifact. - Run the rubric. Read
references/rubric.mdand work through all ten tips. Each has explicit detection commands and 0/1/2 scoring criteria. - Report. Use the output format below.
Prefer batching the cheap filesystem checks into a few parallel Bash calls rather than one call per check. gh is often available for the GitHub-side checks (labels, discussions, releases, Actions); if gh auth status fails, mark those checks UNKNOWN rather than guessing.
Scoring
Each tip scores 0–2:
| Score | Meaning |
|---|---|
| 0 | Absent — the practice is simply not there |
| 1 | Partial — something exists but misses the point (e.g. a CHANGELOG.md of raw commit subjects, or a README with no code sample above the fold) |
| 2 | Good — meets the bar described in the rubric |
Total is out of 20. UNKNOWN checks are excluded from both numerator and denominator — report the adjusted denominator rather than silently scoring an unverifiable item as 0.
Grade bands: 17–20 product · 12–16 solid repo, gaps at the edges · 7–11 works for the author, hostile to newcomers · 0–6 fortress.
Output format
Report in the conversation by default. Write REPO-AUDIT.md into the target repo only if the user asks or passes --write — dropping files into someone's repo uninvited is intrusive.
Lead with the scorecard:
Repo: <name> Ecosystem: <stack> Score: 13/20
1 Discovery ██░ 2 unique name, README pitch is generic
2 Green CI █░░ 1 CI exists, single config, no badge
3 Triage ░░░ 0 no issue templates, Discussions off
...
Then, per tip that scored below 2: what's missing, why it costs you (in the talk's terms — lost users, lost contributors, lost trust), and the smallest concrete fix. Cite real paths (.github/workflows/ci.yml:14).
Close with "Start here" — the three highest-leverage fixes, ordered by (impact ÷ effort). The talk's own advice is explicit: don't implement all ten at once; do one this week and the next one a month later. Respect that. Do not hand back a 10-item work plan.
Rules
- Read-only. Never modify the audited repo. The single exception is
REPO-AUDIT.mdon explicit request. - Verify, don't assume. "Has a CONTRIBUTING.md" is not a pass — open it and check it explains how to build and run tests. An empty template scores 1, not 2.
- No score inflation. The rubric bar is deliberately high. Most healthy repos land 10–14. Saying so plainly is more useful than a generous grade.
- Judge intent, not checklist compliance. A repo with no
CONTRIBUTORS.mdbut a maintainer who thanks people in every release thread is doing tip 9 correctly. Score the outcome. - Small/private repos: tips 1, 5, 8, 10 (discovery, public demos, release marketing, evangelism) may be genuinely irrelevant for an internal tool with three known users. Ask, or mark
N/Aand adjust the denominator — do not penalize a repo for not marketing itself to a public that doesn't exist.
Reference
Source notes: TIPS.md in the repo-to-product repo (talk: https://www.youtube.com/watch?v=DWXlyOd_z88).