Found by the real-repo plausibility audit of a galaxyscope scan of IBM's zopeneditor-sample (COBOL/PL-I/JCL/HLASM/REXX, 51 files analyzed), engine main just after REXX #2504 / PR #3107.
The vector is fine; the presentation is not
risk_documentation (contract: docs/risk_documentation_contract.md, #2908; display alias doc_surface at gitgalaxy/standards/analysis_lens.py:1157) is a genuinely informative measure. Per its own contract it is the weight-share of a file's extracted units a reader cannot recover from documentation — a ratio over units, not a line density. Nothing is wrong with the definition.
The problem is where it lands. Because it reads at or near ceiling on any undocumented codebase (mode 100, median 50 on the sample scan), "Documentation (100.0%)" appears in the Primary Risk Drivers line of all 10 of the top-10 entries, alongside the equally ceiling-defaulted Spec Match (#3111). The line that is supposed to differentiate files instead reprints two constants.
Requested change
Keep computing and reporting it, but reclassify it out of the risk-driver family and into the context/coverage family:
- it should read as "documentation coverage: X% of unit weight undocumented";
- presented beside program-length context, not as a fragility signal;
- and it should stop being eligible for the Primary Risk Drivers line.
Unlike #3111 — spec tags, a convention used by few shops — this vector is informative for nearly every shop. The ask is deliberately reframe, not disable.
Three adjacent asks, deliberately different
So a reader does not conflate them:
| vector |
ask |
issue |
risk_spec_match |
opt-in, default OFF |
#3111 |
| Cumulative Risk composite |
removed |
#3112 |
risk_documentation |
kept, reclassified |
this issue |
Found by the real-repo plausibility audit of a galaxyscope scan of IBM's zopeneditor-sample (COBOL/PL-I/JCL/HLASM/REXX, 51 files analyzed), engine main just after REXX #2504 / PR #3107.
The vector is fine; the presentation is not
risk_documentation(contract:docs/risk_documentation_contract.md, #2908; display aliasdoc_surfaceatgitgalaxy/standards/analysis_lens.py:1157) is a genuinely informative measure. Per its own contract it is the weight-share of a file's extracted units a reader cannot recover from documentation — a ratio over units, not a line density. Nothing is wrong with the definition.The problem is where it lands. Because it reads at or near ceiling on any undocumented codebase (mode 100, median 50 on the sample scan), "Documentation (100.0%)" appears in the Primary Risk Drivers line of all 10 of the top-10 entries, alongside the equally ceiling-defaulted Spec Match (#3111). The line that is supposed to differentiate files instead reprints two constants.
Requested change
Keep computing and reporting it, but reclassify it out of the risk-driver family and into the context/coverage family:
Unlike #3111 — spec tags, a convention used by few shops — this vector is informative for nearly every shop. The ask is deliberately reframe, not disable.
Three adjacent asks, deliberately different
So a reader does not conflate them:
risk_spec_matchrisk_documentation