Comprehension debt is the gap between what your codebase does and what you can explain. It accumulates fastest when AI writes code you only skim. Walk through ten questions across six dimensions and get a Windows-98-style System Properties report — per-dimension health bars, an overall GPA, and a verdict. Optional unlock: a 30-item Comprehension Recovery Checklist mapped to your weakest dimensions.
Pick the answer that matches the project you spent the most time on this week. Each answer carries a grade — Always = 3.0, Often = 2.0, Sometimes = 1.0, Never = 0.0. Switch to the Health tab to see your per-dimension score.
Can you re-read AI-generated code from two weeks ago and explain why each non-obvious decision was made — without re-deriving it from scratch?
When AI generates a non-trivial function, do inline comments capture the why (a constraint, an invariant, a workaround) — not just the what?
Do new AI-written features ship with at least one test that would actually fail if the AI's logic was wrong (not just a smoke test)?
When AI suggests a refactor, do existing tests catch any behavioral regression — or do you find out at runtime?
Do AI-generated variable and function names accurately describe behavior — not just the type, the shape, or a generic placeholder like data, result, or handler?
Could you draw the data flow through one AI-built feature on a whiteboard right now — without re-reading the code first?
When you ask AI to add a feature, does it integrate with existing patterns — or does it bolt on a new sibling system that overlaps with what's already there?
Could you estimate the cyclomatic complexity (or just the branch count) of any function you committed this month — within ±2?
When AI generates a clever solution, can you sketch the simpler equivalent you'd write by hand — and explain why the AI's version is or isn't worth the extra surface?
Could you list every npm / pip / cargo dependency AI added this month — and explain in one sentence each why it was added (not just "AI suggested it")?
Each question targets one of six dimensions: documentation, testing, naming, architecture, complexity, dependencies. Pick the answer that matches your real workflow this week — not the answer you wish was true.
Switch to the Health tab. Six segmented progress bars, one per dimension, plus a GPA on a 3.0 scale and a one-word verdict. The weakest dimension is where you'll get the highest interest if you fix it first.
Send 5,000 sats to the unlock address. Once one block confirms, paste the TXID — the Advanced tab opens, revealing 30 prioritised actions mapped to the dimensions. Work them P0 → P2.
Comprehension debt is the gap between what your codebase does and what you understand. It accumulates fastest when you accept AI-generated code without reading it carefully — the code works, the tests pass, the feature ships, but you cannot explain why a non-obvious decision was made. The term entered wide circulation after Addy Osmani used it in March 2026; this calculator gives you a per-dimension number for it.
Ten questions, four answer levels each (Always / Often / Sometimes / Never), takes about three minutes to walk through. A fifty-question form gets abandoned mid-fill. The ten questions are calibrated to the six dimensions most strongly correlated with maintainability outcomes: documentation, testing, naming, architecture, complexity, dependencies. The score is informational — it tells you which dimension to invest in next, not whether your code is good.
Each answer encodes as 2 bits (Always=3, Often=2, Sometimes=1, Never=0). Ten questions × 2 bits = 20 bits = 5 hex characters: ?cd=<5hex>. URLs round-trip exactly; pasting a teammate's URL pre-fills their answers. Invalid input — wrong length, non-hex, or unparseable — is rejected. Tampered URLs do not silently mutate the form to a blank state.
A 5,000-sat one-time payment unlocks the ADVANCED tab — a 30-item Comprehension Recovery Checklist organized by the six dimensions. Each checklist item is a concrete action that pays down one specific kind of comprehension debt (writing a What-Why-How comment, adding a regression test, renaming a variable). The free score is fully usable; the unlock is the action plan. The same 5,000-sat payment also unlocks the other priced features on Promptshelf (Promptle Hard Mode, Token Tetris Daily Challenge, Stumble Deep Cut, Vibe Code Security remediation guide, AI Review Noise Reduction Playbook, Token Budget Optimization Playbook) — the shared client-side verifier accepts any prior 5,000-sat tx to the address, so paying once gets you all seven. Verified client-side via mempool.space; no account.
No, it is a self-assessment. The score reflects what you say about your codebase, not what your codebase actually contains. The point is to make you walk through six dimensions explicitly, surface the one you under-invest in, and act on it. A team with a low score and a recovery plan is healthier than a team with a high score that never asked the questions.
The Windows 98 System Properties dialog is a familiar visual metaphor for a system health report — tabs, group boxes, segmented progress bars, an OK button at the bottom. Comprehension debt is a system-health problem; the metaphor lands faster than a generic dashboard. The aesthetic is also screenshot-friendly, which helps the score get shared in Slack and Discord channels.
Tip the project. Comprehension Debt Score is part of Promptshelf — a small library of single-file tools for AI coding workflows. If this saved you a debugging hour, send a few sats. Same address as the Advanced unlock; any amount confirms.