The review layer

Three sentences

The study app surfaces flagged sites and flagged participants at every data cut, but nothing anywhere records that a human looked at one, what they concluded, or what they did — so the same rows demand attention again at the next cut and the reasoning behind every decision lives in a meeting, an email, or nowhere. The survey of thirteen safety and monitoring platforms scored ten review-workflow capabilities and found this portfolio has none of them, while the single capability with the broadest support across those platforms is the one that tells a returning reviewer what has changed since they last looked. This page proposes the two smallest pieces of that layer, and asks six questions whose answers determine whether the record is trustworthy or merely present.

Nine of thirteen, and thinner than it sounds

Only nine of the thirteen surveyed platforms touch review workflow at all. The four open-source clinical packages closest to this project — the safetyGraphics family, Roche's teal, Boehringer's DaVinci modules and Biogen's tidyCDISC — carry none of it. What they have instead is state persistence, which is a different thing: teal has named snapshots and report cards, DaVinci has a bookmark manager. Those remember a view. None of them remembers a judgment.

Among the nine that do, the depth varies enormously, and the survey is careful that a platform was scored as having a capability because its documentation describes one. Nothing was tested, and the report says plainly that vendor documentation flatters.

What "since I last looked" turns out to mean

Five platforms carry this capability and the survey describes three genuinely different mechanisms plus one bare assertion. They are worth separating, because the differences are the whole design.

• A watermark belonging to a person. JReview is the only one that ties the comparison to a review mark: a checkbox per patient, and patients with new data since that review highlighted. The grain is the patient. What counts as new data, whether the mark is per-user or shared, and whether it clears itself are not stated.
• A diff between two data batches, with no person in it. clinDataReview compares two refreshes. This is impersonal and needs no review state at all. It is also the only one of the five that is open source and therefore readable.
• Change detection consumed by automation. Veeva raises queries from detected changes. A reviewer never sees a "new since you looked" view; the machine acts on it.
• Movement of an alert across refreshes. Empirica tracks how a signal moves rather than where it stands, which is about the finding's own history rather than about any reviewer's visit.
• Named and nothing more. elluminate's entry is the phrase "identification of data changes since the last review." That is the entire published evidence.

Where each approach breaks

• A checkbox with no content behind it tells you someone ticked a box, not what they saw. When the data changes it either clears — and the reviewer loses a conclusion that may still be correct — or it does not, and the tick silently becomes a lie. Neither branch is recoverable, because nothing recorded what the tick was about.
• A batch-to-batch diff with no person in it answers "what changed last week", which is only the same question as "what changed since I looked" for a reviewer who looks exactly weekly and never misses one.
• A completeness percentage reaches a hundred per cent when everything has been dismissed, so the number rewards the act rather than the finding, and it cannot fall when new data arrives without also punishing a reviewer who is up to date.
• Change detection wired to automation requires an automated consumer. This portfolio publishes static files and has no query system to raise anything into.

The state is not actually mutable, and the snapshots are not actually immutable

The requirement names the central tension: review state is mutable and per-person, while the whole data architecture rests on immutable published snapshots that can be re-run and reproduced. Both halves of that sentence turn out to need correcting, and correcting them is what makes the design small.

Nothing mutable has to be stored

A review is not a state. It is an event: at a moment, a named person asserted something about a named finding as that finding stood in a particular set of data. An event is a fact, and facts do not change. What people want to see is a status — reviewed, escalated, outstanding — and a status is not a stored thing either. It is a fold over the events, joined against whatever the data says now, computed when the page renders.

That leaves two immutable inputs and one derived view, which is precisely the shape the pipeline already has. Nothing in the design ever writes a field twice, and nothing ever needs a lock, a merge or a last-writer-wins rule.

But the snapshots are not immutable, and that is measured

The published site holds three snapshots under the names ps-001, ps-002 and ps-003, and the app addresses history by those names. Reading the publish history of the first one shows it was published once and rewritten four times afterwards. Hashing the results file at each of those five commits shows four genuinely different datasets under the one name.

The rebuild script makes this structural rather than accidental: it deletes every snapshot directory on the published branch, deletes the index that lists them, and re-issues the names from one. A review recorded against a snapshot name therefore has no defence at all. After a rebuild it points at whatever now holds that name, and the page would show a person's name and a date beside data they have never seen.

What a review should point at instead

A finding needs two identifiers and they do different jobs.

• What the review is about. The study, the level, the group and the metric. This is already the ecosystem's own answer: the function that compares results across snapshots declares exactly that four-part key, and it is unique in the published data — every one of the 4,273 rows in the bundled study has a distinct one. It stays the same when the finding gets better or worse, which is what makes persisting and resolved mean anything.
• What the reviewer saw. A digest of the values that were on the screen. This is what makes the entry falsifiable later, and it is what a snapshot name cannot do.

Note what this excludes. The requirement proposes putting the flag into the key. It should not be there: across the three published snapshots, 310 findings carry two different flag values and 13 carry three, so keying on the flag detaches a reviewer's conclusion at precisely the moment the flag flips, which is the one moment they care about. The flag is something the reviewer saw, not something that names the thing they looked at.

The same correction collapses the requirement's second key. It proposes a separate identity for participant-level safety findings, but those already publish through the identical seven columns, with the participant identifier sitting in the group field. There is one key, not two, and it already covers 1,930 published participant findings alongside the site and country ones.

The trap that makes this feature worthless if it is built the obvious way

The obvious implementation hashes the whole result row and reopens the finding when the hash moves. On this data that reverts essentially every finding to unreviewed at essentially every snapshot, because a site that is still enrolling has a different denominator every time the pipeline runs. The feature would then mark everything as changed, a reviewer would learn within two cuts to ignore it, and the capability would be worse than not having it.

The mechanism the requirement admires — a changed row reverting its listing to incomplete — works in the product it comes from because that product watches source data records, where a change means somebody corrected a value. A risk-indicator row is a derived aggregate that moves by construction. Copying the mechanism across that difference without noticing it is the failure mode here.

So materiality has to be declared rather than computed, and it belongs next to the metric's threshold, because deciding what counts as a meaningful move is the same kind of judgment as deciding where the threshold sits. Three tiers are enough.

Two pieces, and the first one is nearly free

Writing it, with no server and no password

The site is static by contract, stated in the requirements, in the publishing notes and in the design record, and it is served from a branch verbatim with no build step. That rules out a form that posts somewhere. It does not rule out writing, because the hosting platform will accept a fully composed file through a link.

This was executed rather than assumed. Opening a prefilled new-file link against the demo study repository opens the platform's own editor with the path and the entry already filled in, under whatever account the reviewer is already signed into. Nothing was committed. No credential is ever handled by the page, and there is no authentication code to write.

Then the failure direction, by binary search on the same link:

A realistic entry carrying the full regulatory field set is 400 characters, which becomes 580 once encoded into a link, so one hand-off carries about thirteen findings. That is a real bound and the design should state what happens above it rather than discover it in front of a user: the page splits a longer session into a second hand-off. It is also the reason the record is one file per review session rather than one file per finding, which has a second benefit — two reviewers working at once never touch the same file, so a conflict between them is not merely unlikely but structurally impossible.

Where the file goes, and why not the obvious place

The study repository has a source branch and a published branch, and the published one is arranged by a script. That script replaces exactly three named directories and copies four named files; it never enumerates the published root to remove anything unknown. A review folder kept at that root would therefore survive every publish — while the rebuild deletes every snapshot directory beside it.

That makes the published branch a survivable address but a bad home, for four reasons that all point the same way: everything on it is world-readable, the pipeline pushes to it without rebasing so a reviewer's commit landing at the wrong moment breaks the next publish, that branch is the one branch policy reserves for your approval so no reviewer could write to it unattended anyway, and it holds generated output rather than authored material.

The review record is authored. It belongs on the source branch with the other authored things, where changes arrive as pull requests on the ordinary lane, and the publish step should carry a derived projection of it onto the site the same way it carries everything else. That resolves the visibility question, the race, and the policy collision in one move, and it costs one thing worth naming: a review recorded on Tuesday does not appear on the site until the pipeline next runs, which today is Monday.

Named honestly, including what it does to the provenance claim

• The site stops being a pure function of the pipeline. Today every number on the page derives from the pinned packages and the named input. With a review layer the page also derives from a record that people wrote. The snapshot tree itself stays untouched — the record is never inside it — but the sentence on the masthead becomes true only of the numbers and not of the page. The provenance chip has to distinguish two sources, and the honest version of that sentence is longer than the current one.
• Snapshot identity has to become real. This is the largest cost and it is owed anyway. Either published snapshots genuinely stop being rewritten, or a digest of the results is published alongside them so a review can name the data rather than the directory. The digest is cheap — a few lines in the publisher — and it has the side benefit of making the immutability claim checkable for the first time.
• A finding's evidence is not in the finding. The summarising step keeps the verdict and drops the reasoning: a participant flagged by the liver-signal metric publishes as three numbers and a flag, while the peak enzyme values, the ratio and the quadrant that produced it do not survive into the published row. A reviewer acknowledging that finding is signing against a row that does not contain the clinical facts. The entry should therefore carry a deep link to the display that does — which the app already supports, and whose source comment already says such links can be pasted into a review comment.
• Integrity is tamper-evident, not tamper-proof. History on a branch can be rewritten by anyone able to force-push. The claim worth making is that the record is attributable, timestamped, and detectably altered under branch protection. Anything stronger would be a claim about a system nobody here has validated.
• No electronic-signature claim. Identity provisioning is not controlled here, signature manifestation is not implemented, and there is no validation package. Declining that in writing is the same posture the change-request work already adopted, and it should be stated in the product's own documentation rather than left to be inferred.
• Every acknowledgement becomes a pull request. That is the audit trail and also the friction. Batching a session into one file keeps it to one request per sitting rather than one per finding, bounded at about thirteen.

What should wait, on the record

Of the ten capabilities, this design proposes two and deliberately defers the rest. A review plan with objectives linked to displays is the rarest thing in the survey and the closest analogue to this project's own traceability, but it needs the record to exist first. Role-based assignment needs roles, which needs accounts. An audit trail with electronic signatures is a gate on adoption rather than a display and is declined above. Participant-level alerting needs a notion of a refresh that this design supplies and should be designed after it. Raising a query back into the data-capture system is out of scope and should stay out. Annotation should never be built at all as a separate feature — an entry with a note is the annotation, and building both would be two records of the same thing. Issue tracking with a documented resolution comes almost free: an escalation opens an issue in the same study repository, which is the mechanism the study-level repository work already proposes for change requests and sign-offs.

Six, each with a recommendation

What starts on each answer

This page is also the answer to the fifth question on the clinical-priorities artifact, which asked whether the review layer becomes first-release scope or is deferred in writing. The recommendation here is the narrow middle: the digest and the record are worth building, the remaining eight capabilities are deferred in writing above, and nothing in this design gates a clinical release.

Three things previously written that this page contradicts

• That the finding key includes the flag. The requirement proposes it for both the risk and safety cases. The ecosystem's own comparison function declares the key without it, and the flag is unstable for a fixed finding across the three published snapshots — 310 findings carry two values and 13 carry three. Putting it in the key breaks review state exactly when the flag flips.
• That safety findings need a second key. They publish through the identical columns with the participant identifier in the group field, so there is one key covering all four levels, and 1,930 participant findings are already published under it.
• That the published snapshots are immutable. Stated on the site and in the design record; contradicted by five commits to one snapshot name carrying four different datasets, and by a rebuild script that deletes the directories and re-issues the names from one.

What was measured here rather than relayed

• The snapshot rewrite. Every commit touching the first published snapshot was listed, and its results file hashed at each one, giving four distinct datasets across five commits.
• The write path. A prefilled link was opened against the real study repository and the editor confirmed to prefill both the path and the content. Nothing was committed. The size ceiling was then found by binary search on the same link, and the entry cost measured against the regulator's field set.
• What survives a publish. The publishing script and the rebuild script were read directly to establish which paths each destroys and which it leaves alone.
• The comparison that already ships. Its definition was read to confirm it takes both row sets as arguments and compares flag levels only.
• The identity claims. Column names, key uniqueness, flag instability, participant-finding counts and the movement of the boundary curve were all taken from the published data and the installed packages rather than from documentation.
• What the platforms do. Taken from the frozen survey, including its own statement that a platform was scored on what its documentation describes and that nothing was tested.
• What this page does not know. Whether any surveyed platform compares against a per-reviewer baseline; the survey does not say, and this page does not claim it.