diff --git a/docs/history/DEVELOPMENT_LOG.md b/docs/history/DEVELOPMENT_LOG.md index 6aed7ed..65bf888 100644 --- a/docs/history/DEVELOPMENT_LOG.md +++ b/docs/history/DEVELOPMENT_LOG.md @@ -32,6 +32,69 @@ written and stay true. It is exempt from review for the same reason a receipt is ## Entries +### 2026-08-18 — Batch 02 shipped: the prediction engine, and three bugs the tests found + +All five Batch 02 issues closed and the milestone closed with them. The app now +ships the engine PRODUCT_PLAN.md §12 specifies rather than the prototype it was +explicitly labelled as. + +**The shape is the design.** `PersonalPredictionEngine` keeps a discrete +probability distribution over candidate start dates, not a date with a margin. +The mode is the forecast, the window is the narrowest span holding 80% of the +mass, and a "Not yet" is the distribution conditioned on what the user said. +§13's requirement — that a "Not yet" updates the date, the window *and* the +confidence rather than shifting a fixed prediction by a day — is not extra work +in that design; it is the only thing that structure can do. + +**It is better, as a number.** `EngineComparisonTest` scores both engines over +the §51 fixtures on every build: mean absolute error 0.67 against 1.00, and the +window contained the actual start 9 times out of 9 against 7. + +**Coverage is the measure, not width — and measuring taught that.** The first +version of the comparison asserted the new windows must not be wider. It failed, +and it was the assertion that was wrong: where the personal engine is wider, it +is right to be, and the baseline answers a history with a suspected missing +period using a two-day window and misses. A window that misses is a broken +promise rather than a tight forecast. + +**Three modelling bugs, each found by a test failing rather than by reading:** + +1. Median absolute deviation alone reads a user alternating 25 and 37 days as + perfectly consistent — half her deviations are zero. Twenty disagreeing + cycles came back High, which is exactly the §15 rule about volume not buying + confidence. Spread is now the larger of MAD and mean absolute deviation. +2. Recency weighting assumes the recent past predicts the near future. For a + variable user that is false, and weighting it equally cost three days on the + §51 variable fixture. Recency is now trusted in proportion to how much her + cycles agree — which is a better statement of what recency weighting is + actually for. +3. A fixed one-day floor on trend detection fired on a 42-day-cycle history + whose medians differed by one day. One day is a real trend at 28 and rounding + error at 42, so the floor is relative to the user's own spread. + +That is now three consecutive pieces of work — the schema guard, the boundary +guard, and the engine — where the thing that found the defect was **running it, +not reading it**. Worth stating as a habit rather than a coincidence. + +**Wired through, not just tested.** `PredictionInput` carries recent absolute +errors and the repository feeds scored errors back in. Without that the app +would store every error it makes and never read one back — measuring accuracy +rather than learning from it, with §12 step 5's widening happening only in a +unit test. + +- **Closed:** #10, #11, #12, #13, #14 — and the `Batch 02 — Prediction Engine` + milestone, which closing the last issue does not do. +- **Next action:** Batch 03 — Core UX. The onboarding flow in §19, the designed + Today screen and its six dynamic states in §21–§22, period start and end + logging in §23–§24, the calendar in §26 and Insights in §27. The working + surface built in Batch 01 is deliberately ugly and says so on screen; it is + the thing Batch 03 replaces. Before starting, file the Batch 03 issues — the + milestone exists and is empty. +- **Blockers:** Unchanged and both need a person. #8, the three branding marks, + which an agent must not fake. #9, the webhook, whose URL and secret are not + readable from this machine — until it is registered an opened `P0` raises no + alert at all. Neither blocks Batch 03. + ### 2026-08-18 — Batch 01 foundation: seven of nine issues, and three guards that were wrong Room, DataStore, the repository layer, period CRUD end to end on a device, and