The constants that encode biology carry no evidence #54

New Issue

Closed

opened 2026-08-20 16:13:30 -05:00 by null · 0 comments

null commented

2026-08-20 16:13:30 -05:00

Owner

What is true now. Several constants in domain/prediction are claims about menstrual physiology, and the tree records only that they were chosen: DEFAULT_LUTEAL_PHASE_DAYS = 14, FERTILE_DAYS_BEFORE_OVULATION = 5, FERTILE_DAYS_AFTER_OVULATION = 1, MAX_USEFUL_UNCERTAINTY_DAYS = 3 (FertilityEstimate.kt), POPULATION_DEFAULT_DAYS = 28.0 (PersonalPredictionEngine.kt), MINIMUM_PLAUSIBLE_DAYS = 10 (IntervalAnalysis.kt), and the choice of a Laplace tail. The code comments argue why the shape is right but cite nothing, so a future reader cannot tell a measured value from a convention.

What to do. Add docs/architecture/SCIENCE.md with a verdict and citation per constant — supported, contradicted, or needs-a-caveat — and state plainly which constants are engineering parameters rather than scientific claims (MULTIPLE_TOLERANCE, UNUSUAL_TOLERANCE) so nobody demands a citation for them later. One substantive change falls out of the audit: POPULATION_DEFAULT_DAYS 28.0 is mildly contradicted (large app-data studies put the mean near 29.3 days, with only a minority of women averaging 28) and should become 29.0 with its citation in the comment.

Traps. BaselinePredictionEngine.DEFAULT_CYCLE_DAYS must stay 28.0 — it is the frozen control, and changing it would silently move the comparison the replacement is measured against. The luteal-phase question (measured means run ~12.4 days against the textbook 14) is filed separately: it shifts what the fertility screen displays and does not belong inside a calibration change-set. A new document fires docs/DOC_TRUST_MAP.md's own review trigger, so the trust-map row lands in the same commit; use the spaced-dash form in the Governs: line, since doc-triggers.py silently ignores a parenthetical gloss.

Verify: docs/architecture/SCIENCE.md exists with a row per constant above, docs/DOC_TRUST_MAP.md points at it, and python3 scripts/doc-triggers.py reports no unaddressed document after the commit.

**What is true now.** Several constants in domain/prediction are claims about menstrual physiology, and the tree records only that they were chosen: `DEFAULT_LUTEAL_PHASE_DAYS` = 14, `FERTILE_DAYS_BEFORE_OVULATION` = 5, `FERTILE_DAYS_AFTER_OVULATION` = 1, `MAX_USEFUL_UNCERTAINTY_DAYS` = 3 (FertilityEstimate.kt), `POPULATION_DEFAULT_DAYS` = 28.0 (PersonalPredictionEngine.kt), `MINIMUM_PLAUSIBLE_DAYS` = 10 (IntervalAnalysis.kt), and the choice of a Laplace tail. The code comments argue *why the shape is right* but cite nothing, so a future reader cannot tell a measured value from a convention. **What to do.** Add docs/architecture/SCIENCE.md with a verdict and citation per constant — supported, contradicted, or needs-a-caveat — and state plainly which constants are engineering parameters rather than scientific claims (`MULTIPLE_TOLERANCE`, `UNUSUAL_TOLERANCE`) so nobody demands a citation for them later. One substantive change falls out of the audit: `POPULATION_DEFAULT_DAYS` 28.0 is mildly contradicted (large app-data studies put the mean near 29.3 days, with only a minority of women averaging 28) and should become 29.0 with its citation in the comment. **Traps.** `BaselinePredictionEngine.DEFAULT_CYCLE_DAYS` must stay 28.0 — it is the frozen control, and changing it would silently move the comparison the replacement is measured against. The luteal-phase question (measured means run ~12.4 days against the textbook 14) is filed separately: it shifts what the fertility screen displays and does not belong inside a calibration change-set. A new document fires docs/DOC_TRUST_MAP.md's own review trigger, so the trust-map row lands in the same commit; use the spaced-dash form in the `Governs:` line, since doc-triggers.py silently ignores a parenthetical gloss. Verify: docs/architecture/SCIENCE.md exists with a row per constant above, docs/DOC_TRUST_MAP.md points at it, and `python3 scripts/doc-triggers.py` reports no unaddressed document after the commit.