Comprehension-Debt System of Record
See how much of your codebase no human understands.
AI agents are writing most of your new code. The code may be fine — but every unreviewed merge widens the gap between what your codebase does and what your team actually understands. That gap is comprehension debt. Install the read-only GitHub App and Fathohm maps yours from your own commit and review history — then gives your team a way to pay it down.
34% of this example repo, no human currently understands.
The Map: every file, sized by lines of code, colored by comprehension score.
Illustrative Map — example data, not a real customer repo. Yours is built from your actual commit and review history.
Riskiest blind spots in this example
| Path | Score | Authorship | Why it's risky |
|---|---|---|---|
| services/billing/reconcile.ts | 0.06 | Agent-authored | Agent-authored, merged with 0 review comments. Touches payments. |
| services/billing/invoices.ts | 0.14 | Agent-authored | One-line approval, no discussion. |
| services/sync/engine.ts | 0.15 | Agent-authored | 2,000-line agent PR, approved in 4 minutes. |
| services/billing/tax.ts | 0.16 | Agent-authored | Single reviewer, skimmed. |
| services/sync/conflict.ts | 0.22 | Agent-authored | Only reviewer left the team in March. |
A score you can take apart
Comprehension is scored 0–1 per file, deterministically, from four visible factors. No black boxes: the same history always produces the same score, and every number decomposes on hover. A file below 0.30 is a blind spot — code no human on your team currently understands.
Human review depth
weight 0.40Substantive review counts; approval-without-comment doesn't. Agent-authored code merged with zero review comments scores 0 here.
Human author recency
weight 0.25When a human last meaningfully wrote here. Decays over 180 days — understanding fades.
Bus factor
weight 0.25How many distinct humans have had substantive contact with this code.
Question answerability
weight 0.10Verified comprehension: someone opened the file, answered three questions about it, and rated how well they could. The only factor a human moves on purpose — and it decays, so it has to be re-earned.
Measure, then notice
A number nobody acts on is a vanity metric. Fathohm maps the debt, then tells you every week what moved and where the risk concentrated.
Measure
The Map
Every file, sized by how much code it holds and coloured by comprehension score. Hover any cell for the factor breakdown behind its number; switch the colouring to authorship to see what agents wrote. Directories aggregate, so a repo with thousands of files still reads at a glance.
Notice
The weekly digest
Once a week Fathohm files a digest to your dashboard inbox: your top new blind spot, how your debt moved since last week, the three riskiest paths, and the one file worth picking up next. Trends chart those same snapshots over time.
Debt you can actually pay down
Measuring comprehension debt is the easy half. The hard half is that the only thing which genuinely reduces it is a person understanding the code. So the paydown loop is built around a human answering questions — not a tool making a number go down.
Step 1
Pick a file
Your work queue ranks every blind file worst-first — highest churn, then size — so you're never guessing where to start. The weekly digest picks out the single one worth doing next.
Step 2
Read the briefing
Fathohm generates a module briefing from your source, read transiently and never stored. It's the orientation a teammate would have given you, if one still had it.
Step 3
Answer three questions
Then rate how well you could answer each — could, partially, couldn't. That rating is what feeds question answerability, and it decays: comprehension has to be re-earned, not banked.
Not every blind spot is worth paying down. Accept the risk with a reason and the file leaves your queue — but the blind-spot number does not bend. Accepted is not understood, and the Map keeps saying so.
Scales with your team
When more than a few people share a codebase, comprehension needs governing as well as measuring.
Comprehension policies
Declare a floor for a critical path — nothing under auth/ may score below 60. Evaluation is deterministic and names the exact files and scores that breached it, never a bare pass or fail.
Decision ledger
Accepted risks, paydown sessions, and policy edits merge into one sorted history of who governed what, when, and why. Exportable.
Ownership mapping
Your CODEOWNERS file, parsed with GitHub's own last-match semantics, so every blind spot shows who owns it.
Roles
Admin, member, viewer. Roles gate actions — accepting a risk, running a session, editing a floor — never what you can see. A viewer reads the same numbers an admin does.
Why this is safe to install
Read-only, always
The GitHub App requests read scopes only. It never writes to your repos, never executes your code, never opens PRs.
Your source is never stored
We ingest commit and review metadata — paths, events, review depth. Source code is read transiently for module summaries and never persisted.
No black-box scores
Every score decomposes into its factors, everywhere it appears. If we can't show you why, we don't show you a number.
Correctable by design
Authorship detection (co-author trailers, agent committer signatures) is published openly, and you can correct any label we get wrong.
Get the Map for your repos
Install the read-only GitHub App on the repos you want mapped. Fathohm backfills your commit and review history, scores every file, and your Map fills in as the backfill lands. It never writes to your repos, never executes your code, and never opens PRs.