Codebase Value Audit

codebase-value-audit

Turns "our repo is N lines, is that bad?" from a vibes debate into an audit. The core move: a raw LOC number is meaningless until (a) the measurement lens is pinned, (b) the product surface it bought is inventoried, and (c) every line is attributed to one sub-product and judged against what a standalone alternative would cost. The output is a report where the verdict is per-block, not global — because the honest answer is always "these 4 blocks are gold, these 4 deserve a discount."

When to use

• Someone quotes a repo-wide LOC figure and asks if it's reasonable.
• Two people quote different LOC figures for the same repo and both are "right" (different lenses) — reconcile before arguing.
• Deciding where to cut: which subsystems dilute maintenance attention.

Not for: per-PR review, performance work, or dead-code sweeps alone (knip/depcheck do that); this skill tells you which blocks deserve a sweep.

Inputs

• Repo root (git-tracked; works on monorepos).
• Optional: the number the requester believes ("we have 800k lines") — you must reconcile your count with theirs, not just assert your own.

Files provided

• scripts/count-pure-loc.sh — strict source-file list + pure-code line count (3 lenses printed side by side).
• scripts/bucketize.py — attributes every file to the first matching bucket prefix and sums pure-code lines per bucket.
• scripts/drill-bucket.py — aggregates one bucket's lines per directory at a chosen depth; mandatory before verdicts (step 4).
• scripts/render-report.py — renders the final report as a standalone HTML file (light/dark, verdict chips, share bars) from a JSON data file; schema in references/report-data.example.json.

Workflow

textCopy code
[1] Pin the lens        3 counts: tracked-total / non-test / pure-code
[2] Inventory surface   parallel read-only agents, one per layer
[3] Attribute lines     bucketize.py: every line -> exactly one bucket
[4] Verdict per block   5 tiers, judged vs standalone-alternative cost
[5] Report              JSON data -> render-report.py -> HTML + open

[1] Pin the lens

Run scripts/count-pure-loc.sh <repo-root>. It prints three numbers:

1. Tracked total — all git-tracked TS/JS lines.
2. Non-test physical — minus tests/fixtures/e2e/scripts/mocks/ stories/.d.ts.
3. Pure code — minus blank and comment-only lines.

These differ by 2x+ on a healthy repo (1.84M / 1.06M / 836k on the repo this skill came from). When the requester's number differs from yours, find which lens produces their number and say so explicitly — "your 800k is lens 3, my 1.84M is lens 1, both correct" ends the argument; a counter-assertion restarts it. All later steps use lens 3.

Also record: test:code ratio, and the largest data-as-code files (model catalogs, locale tables, generated schemas) — they surface in step 4.

[2] Inventory the product surface

Dispatch parallel read-only agents (Explore-type), one per layer, e.g.: web client (routes/stores), server (routers/services/modules), desktop + CLI, shared packages, and docs/changelog (the marketed feature list — this one cross-checks the code-derived inventory against what the product claims to ship; discrepancies are findings). Each agent returns a breadth inventory: surfaces, one-liners, and a "full sub-products" shortlist — no code review, no line counts.

Merge into a sub-product list (typically 15–25 entries). A sub-product is something that could be a standalone company/tool: an eval platform, a bot gateway, a document editor — not a feature like "dark mode".

[3] Attribute every line

Copy scripts/bucketize.py, fill in the bucket → path-prefix table from step 2's inventory, run it against the file list from step 1. Rules:

• First match wins; order buckets specific → general.
• One catch-all infra bucket with prefix "" must be last; inspect its breakdown output — anything large hiding in it means a missing prefix.
• Cross-layer buckets are the point: one sub-product's bucket lists its frontend routes, its stores, its server services, its packages, and its CLI commands together.
• Expect ±10% precision; say so in the report. Sum must equal lens-3 exactly (the script guarantees it — every file lands somewhere).

[4] Verdict per block

No verdict without a drill-down. Before judging any bucket ≥ ~15k lines, run scripts/drill-bucket.py <file-list> <depth> <prefix...> and scan its top directories for the five water categories:

Bucket-level verdicts issued without this pass systematically miss mixed buckets: a "settings" bucket can be 60% provider forms + squatting feature pages + dead routes, and the whole-bucket verdict ("necessary cost") will be confidently wrong. Parallelize: one read-only subagent per 2–3 buckets, each returning findings with line estimates and file-path evidence; require them to verify DEAD claims and to say "clean" when a category is empty — invented water is worse than missed water.

Then refute before publishing. Every water claim from the first pass gets attacked in a second adversarial round: prompt agents to disprove each claim with import graphs, normalized diffs, and actual-wiring traces. Expect casualties — in the audit this skill came from, 5 of 8 first-round claims fell (a "duplicate subsystem" was a dependency; "two workflow generations" were layers; an unused-keys report was 43% false positives). Publish only claims that survive, and record the refuted ones in the report as corrections — an audit that shows its own overturned accusations is more credible, not less.

Then judge each sub-product's pure-code count against what acquiring that capability standalone would cost (build or adopt), not against zero. Five tiers:

Also assemble the squeeze list: concrete removable waste with line estimates (coexisting old/new generations of a subsystem, overlapping sibling services, data-as-code to externalize, convention violations, unused i18n keys, stale packages). This is the actionable output.

[5] Report

Lead with the global verdict and its split (e.g. "70% worth it / 13% core / 18% discounted / 8–10% pure squeeze"). Then: lens reconciliation, the ranked table (lines, share, verdict chip), tier commentary, squeeze list, and a closing that answers the requester's actual question. If they invoked an "AI era = fewer lines" thesis, engage it honestly: writing cost fell, review/maintenance cost didn't; the metric that matters is features per maintenance unit, and a ~1:1 test ratio is agent-era scaffolding, not bloat.

To ship it as a page: fill a JSON data file following references/report-data.example.json (in prose fields [[…]] renders bold, ((…)) renders accent-highlight), then

bashCopy code
python3 scripts/render-report.py report-data.json report.html && open report.html

Output is self-contained HTML (inline CSS, system fonts, light/dark). When a verdict gets challenged and revised, keep the row, annotate it (REV note in eyebrow/footer + a breakdown in its sub), and re-render — an audit that silently rewrites itself loses its authority.

Common pitfalls

Verification

• The three lens counts are internally consistent (lens1 > lens2 > lens3) and the requester's number is mapped to one of them.
• Bucket sums equal the lens-3 total exactly; file list was sort -u'd.
• Infra/catch-all breakdown inspected; nothing unexplained > ~5%.
• Every bucket ≥ ~15k lines went through the drill-down pass; each water finding carries a category, a line estimate, and verified evidence paths.
• Every sub-product has: lines, share, tier verdict, and a one-line justification referencing a standalone alternative or a concrete waste observation.
• Squeeze list items each carry a line estimate and a concrete fix.
• Report states the ±10% attribution caveat and any excluded scopes (e.g. closed-source stubs).
• render-report.py output opens cleanly in a browser; row count, total, and share bars match the bucketize output.