codebase-value-audit

name	codebase-value-audit
description	Use when asked whether a codebase's size is justified — "is 800k lines reasonable?", "audit our LOC", "are we bloated?", "值不值" — or when a LOC number is being used in an argument and nobody agrees what it measures. Produces a defensible per-sub-product accounting: strict line counts, a product-surface inventory, every line attributed to exactly one sub-product, and a worth verdict per block.
metadata	{"author":"innei","version":"1.0.0"}

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

[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:

Category	What it looks like
DEAD-ROUTED	deprecated pages/components still imported or routed — verify with grep against router configs and import sites, never by name alone
DATA-AS-CODE	large TS files that are pure declarations (catalogs, menus, prompt text)
SQUATTER	content semantically belonging to another domain living under this bucket's paths (feature pages under a settings route)
PARALLEL-DUP	two generations/implementations of the same thing coexisting
OVERSIZED	files past the repo's own size convention — count and total them
FIXTURE-IN-PROD	test fixtures / dev harnesses living outside test dirs, counted as product code

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:

Tier	Criteria
core asset	Directly implements the product's differentiation; rebuilding or adopting would cost more; high leverage per line
market price	Table-stakes capability at a normal size for what it does
risk bet	Coherent and well-built, but its value depends on an unproven product thesis — flag "watch usage data"
discount	Competes head-on with dedicated products without an edge, or carries measurable waste (data-as-code, duplicated generations, copy-paste variants)
necessary cost	Settings, auth, base layer — nobody loves it, nothing works without it; judge only its share (base layer ≤ ~20% is healthy)

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

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

Mistake	Fix
xargs wc -l | tail -1 as the total	xargs batches into multiple wc calls; tail -1 returns the last batch only. Sum with awk '$2 != "total" {s+=$1}'.
Counting merge-conflicted files 3x	git ls-files lists each unmerged file once per stage. Always sort -u the file list.
Arguing totals before pinning the lens	Both parties are usually right under different lenses. Reconcile first (step 1), then argue.
Running the counting script from the wrong cwd	Relative paths silently open()-fail and count 0 per file; totals become 0 without an error. Run from repo root; treat an all-zero bucket table as this bug, not as truth.
Treating a high test share as waste	~1:1 test:code is the agent-era signature — it's the guardrail that lets agents keep writing. Cut discipline debt, not tests.
Data-as-code inflating "logic"	Model catalogs, locale tables, generated schemas are declarations. Measure them separately and recommend externalizing, or the density math is wrong.
Inventorying from code only	Also sweep docs/changelog/README with an agent — the marketed surface reveals sub-products the directory names hide, and mismatches are findings.
Catch-all bucket swallowing a subsystem	Order prefixes specific → general; always print the infra-bucket breakdown and chase anything unexpectedly large.
Verdict by size alone	A 10k-line block can be the highest-leverage asset (device gateway) and an 80k block half-waste (provider variants). Judge vs standalone-alternative cost.
Global verdict only	"Worth it overall" helps nobody decide anything. The per-block table with tiers is the deliverable; the global number is its summary row.
Defending a challenged verdict without drilling down	When a block's size surprises the requester ("why is settings 20k?"), re-aggregate that bucket one directory level deeper before answering. Route-named buckets often hide squatters: provider forms, feature pages living under a settings route, deprecated-but-routed dead pages. The challenge is usually a real finding.
Trusting a static "unused" report	An unused-i18n-keys report was 43% false positives: dynamic key construction, string-literal keys inside config objects, and plural suffixes all defeat static detection. Sample-verify against those three mechanisms before acting; a report whose own statistics are self-contradicting (usage rate > 100%) is telling you something.

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.