D0029 — The review layer

[obotclaw[bot]]

The app finds the risks and then forgets that anyone looked. Of the ten review-workflow capabilities the platform survey scored across thirteen platforms, this portfolio has none — the survey's strongest single finding — and the requirement it produced has had all seven of its design decisions open since 29 July.

This is the design pass. Nothing was implemented.

The requirement frames the hard problem as mutable review state living beside immutable snapshots. Measuring it moved the problem: the snapshots are not immutable. The published snapshot named ps-001 on the demo study was published once and rewritten four times afterwards, and hashing its results file at each of those five commits gives four genuinely different datasets under one name — 1,898 rows, 1,898 again, then 1,918, 1,920 and 3,835 — while the rebuild script deletes every snapshot directory and re-issues the names from one. A review recorded against a snapshot name would, after any rebuild, assert that a named person approved data they never saw.

The good news is that the useful build is very small. The snapshot comparison already ships and already takes both sets of rows as its arguments, so handing it the snapshot a reviewer last signed, instead of last week's, turns an impersonal weekly diff into a personal one with no change to the function.

The six questions, each with a recommendation on the page:

RL1 — where the record lives. Authored on the study's source branch and projected to the site on publish, versus written straight to the published branch, versus issues, versus an external store. Recommended: authored on the source branch — it puts review on the ordinary merge lane, keeps the published branch generated, and lets the projection decide what becomes public.

RL2 — what a review points at. A digest of the results the reviewer saw, versus the snapshot name, versus the data-cut date. Recommended: the digest. It is the only option that makes a false record impossible rather than merely discouraged, and two of the three published snapshots share a date so the date cannot tell them apart.

RL3 — what brings a finding back. Three tiers — the flag always reopens, magnitude beyond a declared tolerance reopens, everything underneath is noted only. Recommended, because hashing the whole row reverts every finding to unreviewed at every snapshot: an enrolling site changes its denominator every cut.

RL4 — what becomes public. The demo study is a world-readable repository served verbatim, so a review is published rather than stored. Recommended: publish the fact and the controlled reason, hold free text behind a per-study switch that defaults to off. This is the question with real downside risk.

RL5 — who is a reviewer. Hosting-platform account holders only, said in writing, plus a publish check that refuses an entry whose named author is not its committer. Recommended: yes, and say so plainly.

RL6 — the number at the top. Outstanding findings new or changed since that reviewer last signed, versus a percentage-reviewed tile. Recommended: the outstanding count — a number a person can drive to zero by doing the work, and that cannot be inflated by doing nothing.

The page also answers the fifth question on D0026, which asked whether the review layer becomes v1.0 scope or is deferred in writing: the digest and the record are worth building, the remaining eight capabilities are deferred in writing, and nothing in the design gates a clinical release.

Three things previously written are contradicted on the page: the requirement puts the flag in the finding key and it should not be there; the requirement proposes a second key for participant-level safety findings and they already publish through the identical columns; and the per-reviewer comparison is this programme's own proposal rather than something any surveyed platform is documented as doing.

Answer in words here or in chat — quoting an ID (D0029.1 through D0029.6) helps, but is not required.

https://jwildfire.github.io/obot.roadmap/reports/decisions/2026-08-27-review-layer/

---

Drafted by 👯🤖 Claude Code (Claude Opus 5, worker W0139). Not reviewed by @jwildfire before publication.