Comprehension Coverage

Module. A meaningful part of a system that people reason about, for example payments, login or search. A product typically has 20 to 50. Modules MAY start as code folders and be refined by hand.

Critical module. A module the organisation marks as one whose failure is costly. Coverage is computed over critical modules only.

Holder. A current member of the organisation. A person who has left MUST NOT count toward any score after their leaving date.

Evidence. A recorded event that shows a holder's understanding of a module (section 2).

Understanding score. A number from 0 to 100 for one holder on one module (section 3).

Each piece of evidence adds points to the holder's score on that module.

Explain-back checks SHOULD be written from the specific change; SHOULD test consequences or intent rather than names or syntax; and SHOULD be answerable in under a minute by someone who understands the code. Each check MUST have a reference answer and grading checklist fixed before it is sent.

Authorship alone MUST NOT earn more than 5 points. In systems where AI writes a significant share of code, having written it is weak evidence of understanding.

With no new evidence, a score decays exponentially with half-life H:

s(t) = s₀ · 0.5^((t − t₀) / H)

where s₀ is the score immediately after the most recent evidence, at time t₀. New evidence worth p points sets the score to min(100, s(t) + p).

A holder understands a module at time t when s(t) ≥ θ. Just before a score would fall below θ, an implementation SHOULD offer a short refresh check. After each successful refresh, H is multiplied by g, so people who keep their understanding are asked less and less often.

H₀ = 90 days    g = 1.6    θ = 60

A score's confidence is the number of independent pieces of evidence recorded within the last 2H. A score with fewer than two MUST be labelled unverified wherever it is shown.

Scores inferred from history alone (commits, reviews, incident ownership) without direct evidence MUST be labelled estimated. Estimated scores MAY be shown to help an organisation start, but MUST NOT count toward reported coverage.

For module m at time t, let n(m, t) be the number of holders who understand it.

healthy   n ≥ 2
at risk   n = 1
red       n = 0

n(m, t) is the module's real bus factor: verified, not inferred from who wrote the code.

coverage(t) = |{ critical m : n(m, t) ≥ 2 }| / |{ critical m }|

Coverage is reported as a percentage. An organisation MAY weight critical modules (for example by revenue at stake) and report weighted coverage, Σ wₘ·[n ≥ 2] / Σ wₘ. A report MUST state which variant it uses.

• Individual scores and answers MUST be visible only to the individual, unless they choose to share them.
• Team and company views MUST show only module statuses, counts and coverage.
• For handover and on-call planning, an implementation MAY show whether a named person is covered on a module: yes or not yet, and not the score. This exception MUST be disclosed to the people measured.
• The measures in this document MUST NOT be used to evaluate individual performance.
• Free-text answers SHOULD be deleted within 90 days; scores and evidence metadata MAY be kept while the person is employed.
• Where employee representatives must be consulted, for example works councils, implementations SHOULD document data flows and visibility rules for them.

A measure is only useful if it predicts what it claims. Implementations SHOULD test, on their own data, that incidents in healthy modules are resolved faster than incidents in red ones, and SHOULD adjust evidence points and parameters when they are not. Calibration methods and results SHOULD be published with sample sizes and ranges.

A coverage report MUST include the as-of date, the number of critical modules, the coverage figure and variant, the parameter values and specification version, and the share of scores labelled unverified.

{
  "spec": "comprehension-coverage/0.1",
  "as_of": "2026-10-14",
  "variant": "plain",
  "parameters": { "half_life_days": 90, "refresh_growth": 1.6, "threshold": 60 },
  "critical_modules": 6,
  "healthy": 4,
  "at_risk": 1,
  "red": 1,
  "coverage": 0.67,
  "unverified_share": 0.12
}

This is a first public draft. Parameters will change as evidence accumulates, and every change will be versioned with its reasons. Criticism is the point of publishing it.

Comment on this draft · v0.1, 14 October 2026: first public draft.