Generated from folio-assistant-core/collab/processes/content/content-change-review-committee.bpmn by gen-processes-viz.ts — do not edit here. All processes · folio-assistant-core processes

Committee review of a content change

Process_ContentChangeReviewCommittee · strict (defaulted) · 10 step(s)

The review committee’s review of one staged content change, ending in an approval or a request for changes: compare staged against main, slice the change and review each slice, settle withdrawn comments and disputed findings, gate on coverage, review the editorial dependencies and the impact, and decide.

Called from content-change-review when the author submits. Which end it reaches is what the caller’s GW_CommitteeApproved reads. Organising the review is the review coordinator’s lane and deciding it is the committee’s. Merging is not here: it is a separate, confirmed act in content-change-review-publish.

BPMN diagram: Committee review of a content change

How it connects

Lanes — who acts

lanerolewhat it does here
Review CommitteereviewerCompares staged against main, reviews the slices it is assigned (review-task.bpmn, one call per slice), takes a disputed finding to adjudication, judges the impact assessment, and decides. Task_Approve records the approval; merging is a separate, confirmed act in the publish phase. A rejection ends this phase with changes requested, and the caller routes it to Task_Iterate in the agent’s lane rather than to the author.
Review Coordinatorreview-coordinatorOrganises a review large enough to need organising, and decides nothing about the content: ingests the reviewers’ tagged comments, slices the change into pieces a reviewer can hold, assigns each slice to a review lane, and watches coverage until every changed block has a verdict or a reasoned waiver. A separate role from the editor: organising a review and deciding its outcome are different accountabilities.

Steps

Every one of the 10 step(s) is documented.

steplaneskill / sub-processwhat it does
Compare main vs staging
Task_CompareBeforeAfter
Review Committeestaging-review
visual-diff
rendered-impact
The review starts from the Change Set’s RENDERED list (skill
rendered-impact): every rendered file the change alters, predicted
from each renderer’s dependency cone and checked against the build.
The reviewer opens every content page on it, not only the pages the
author mentions; index files are listed but not reviewed. An input
the renderer could not place is shown as not known, never as no
change.
Review committee opens both URLs side by side:
- Main site: <pages-url>/ (current published state)
- Staging: <pages-url>/branches/<branch-slug>/
The staging banner shows the commit SHA so they can verify
what they are reviewing matches the PR. A changed figure, diagram
or table is also pictured before and after on the review page,
with the share of changed pixels in words (skill visual-diff,
Tool folio-block-screenshots). Anything the staging job cannot
picture (page chrome, scroll behaviour, a PDF page, an IG page) is
in the agent’s before/after preview (skill before-after-preview).
Ingest tagged review comments
Task_IngestComments
Review Coordinatorreview-commentsEvery PR conversation comment that starts with block: <label> becomes a review-comment/1.0.0 todo (open), idempotently, and is published with the preview as review-comments.json. The staging workflow runs this on every push and on every tagged comment; the coordinator owns that it has run before slicing, because the slices are cut around what reviewers have already said. This is the ingest transition of REVIEW_TRANSITIONS. Uses folio-review-comments.
Slice the change and assign reviewers
Task_SliceAndAssign
Review Coordinatorreview-heatmap
staging-review
rendered-impact
From the ChangeSet, its rendered list (skill rendered-impact: each changed rendered page is assigned like a changed block) and the heat map on the review page: cut the change into slices a reviewer can hold (usually a section, or a run of sections where the heat map clusters), and assign each slice to a review lane by what it contains — clinical content to a clinical SME, a decision table to a QC reviewer, prose to a narrative reviewer. A block that needs no review (a pure rename, say) is WAIVED here with a written reason, which is what the coverage gate counts. Re-entered from GW_Covered when coverage is incomplete: the uncovered blocks become new slices.
Review each slice
Call_ReviewSlices
Review Committeecalls Review task
content-review
review-comments
review-task.bpmn, once per slice, in parallel lanes by role. What kind of thing changed decides which review the slice descends into; the reviewer takes on that inner lane’s role for the call only. Each reviewer gives the slice’s blocks a verdict, and comments on the pull request with the block: tag where something needs saying.
Withdraw a review comment
Task_WithdrawComment
Review Committeereview-commentsThe reviewer who made a comment takes it back (it was a misreading, or a later slice answered it). Recorded with folio-review-comment-move --to withdrawn, committed to the edit-set’s feature branch like every status change. This is the withdraw transition of REVIEW_TRANSITIONS.
Adjudicate the disagreement
Call_Adjudication
Review Committeecalls Adjudication
adjudication
adjudication.bpmn. When the editor and a reviewer, or two reviewers, disagree about a finding, an adjudicator settles it and records why; the review comment moves to adjudicated with the Decision that closed it.
Permitted answers: stands — the finding is right and the author addresses it; withdrawn — the finding is wrong and the comment closes. Recorded on the comment, not branched: either way the flow goes on to the coverage check.
Review the editorial dependencies
Task_ReviewUses
Review Committeeuses-editorial-reviewuses[] is what a READER must have read to follow the block — never
populated from the formal dependency graph. Once every changed block
is covered, the committee checks the editorial dependencies of the
change as a whole before judging its impact. Reading order is a
property of folio content, so the step belongs to the content
process, which reaches the harness’s review by calling DOWN into
review-task.
Review impact assessment
Task_ReviewImpact
Review Committeecontent-reviewCommittee reviews the agent’s impact assessment:
- Were all downstream effects identified?
- Are the indicator changes acceptable?
- Does the logic change match the narrative intent?
Request changes
Task_RequestChanges
Review Committeecontent-review
content-review
Committee provides feedback. PR stays open.
Author and agent iterate further.
Approve
Task_Approve
Review Committeedecision-auditThe committee approves the change: the judgement, recorded with the
evidence it rests on. Approving is not merging: a self-authored
change cannot be approved through GitHub’s own review (the approver
may not be the PR’s author), and a merge needs the owner’s explicit
confirmation whoever approved.

Decisions

Every one of the 4 decision(s) is documented.

decisionwhat decides itbranches
A comment withdrawn?
GW_Withdraw
Asked after the slices are reviewed: did a reviewer withdraw a comment? Yes records the withdrawal first; either way the flow then asks whether a finding is disputed.Yes → Withdraw a review comment
No → GW_Disputed_Join
A finding disputed?
GW_Disputed
Is any finding disputed between author and reviewer? Yes goes to adjudication; No goes on to check that every changed block was reviewed.Yes → Adjudicate the disagreement
No → GW_Covered_Join
Every changed block and page reviewed?
GW_Covered
Computed, not chosen: decisions/review-coverage-gate.dmn reads uncoveredBlocks (changed blocks with neither a verdict nor a reasoned waiver) and openDefects, and, where the build published a rendered impact, unreviewedPages, undeterminedInputs and missedPages with their rendered and measured statuses (skill rendered-impact). Resolved comments are not coverage, and coverage is not approval — that is GW_Approved.no → Slice the change and assign reviewers
yes → Review the editorial dependencies
Changes approved?
GW_Approved
The committee’s decision on the impact assessment. No requests changes; Yes approves.No → Request changes
Yes → Approve

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev