Generated from
folio-assistant-core/processes/content/contributor-feedback.bpmnbygen-processes-viz.ts— do not edit here. All processes · folio-assistant-core processes
Contributor feedback on a working draft
Process_ContributorFeedback · strict (defaulted) · 9 step(s)
A document is still being written, and the Authoring Committee gives
feedback on it in a shared Contributor Feedback sheet. This is what
happens to ONE change set, one row of that sheet: a member starts it
with a title, the sections it is about and their feedback; the agent
proposes a direction; an Editor lets the agent edit; the agent makes the
edit in the row’s one pull request, whose staging preview shows what
changed; the committee answers on the row; and an Editor lets the agent
merge. If the row’s feedback changes after the agent wrote its
proposal, the proposal is marked stale and the row’s Ready for agent
goes back to No, so the agent proposes again and an Editor decides
again. The sheet’s colours follow the lanes: Blue for the committee,
Green for the agent, Orange for the Editor. Skill: review-sheet-script.
How it connects
- Called by: Review and publish a folio, Review-log watch
- Calls: none
- Presented on: no docs page section shows this diagram
- Running instances: none recorded
Lanes — who acts
Steps
Every one of the 9 step(s) is documented.
| step | lane | skill / sub-process | what it does |
|---|---|---|---|
Start a change-set rowTask_StartRow | Authoring Committee | review-sheet-script | A member adds a row on the Contributor Feedback tab: a title, the Selected Sections it is about (a dropdown from the document’s table of contents) and their feedback in their own Blue column. The script gives the row its Change-set id and links each section. |
Propose a directionTask_Propose | Authoring agent | review-sheet-script | Reads: the row (Title, Selected Sections, the Contributor Feedback columns, Disposition) and the sections it names. Writes: a proposed direction in Feedback (agent) (Green), and the row’s feedback basis on the Agent tab, so the script can tell when the feedback has moved on. A question for people goes in Feedback (agent) as a Decision needed block with options and a recommendation, and the row’s Agentic status becomes Needs human; a chat card may repeat it, but the sheet is the record. An answered question leaves the feedback: its decision is added to the change set’s Disposition (change set) on the Agent tab, shown in Disposition (agent), whose decision history is appended to and never removed. It ends with Record agent step (record-agent-step.bpmn): the Agent tab row first, then Feedback (agent) from it, then the sheet read back, never Feedback (agent) alone. |
Set Ready for agent to YesTask_ReadyForAgent | Editor | review-sheet-script | An Editor agrees the direction and sets the row’s Ready for agent (Orange) to Yes. Person-only: the agent never sets it. |
Edit the document in the row’s pull requestTask_EditInPullRequest | Authoring agent | review-sheet-script | One row, one branch, one active pull request: the agent edits on the row’s branch and opens its pull request, or updates it when the row comes round again. A closed pull request the committee wants back is reopened, or replaced by a new one on the same branch; earlier ones stay listed in Agentic status. Agentic status (Green) says where it is, and Staging review opens the preview’s what-changed page. Before the preview is staged, the agent writes the change set’s Disposition (change set) on the Agent tab: one line per feedback item, starting from the people’s Blue Disposition, after an optional Overall statement; the sheet shows it in Disposition (agent) and flags any item without a disposition, or one that differs from the people’s. It ends with Record agent step (record-agent-step.bpmn): the Agent tab row first, then Feedback (agent) from it, then the sheet read back, never Feedback (agent) alone. |
Review the preview and answerTask_AnswerPreview | Authoring Committee | review-sheet-script | Members read the preview and answer in their Blue columns, or leave them as they are when the change is right. They record the row’s Disposition (Blue): Pending, Accepted, Partially accepted, Not accepted, Noted, Duplicate or Out of scope. |
QA gate: check dispositions and PRTask_QaGate | QA reviewer (independent) | review-sheet-script | Reads: the change set’s Disposition (change set), the people’s Blue Disposition and feedback, the pull request’s diff at its head commit, and the staging QA report. Checks that every feedback item has one disposition; that each agrees with the people’s Blue Disposition; that each Accepted or Partially accepted item has the change in the diff, and a Not accepted, Noted, Duplicate or Out of scope item has none; that the diff changes nothing no disposition accounts for; and that the QA report for the staged commit has no failing gate. Writes: QA gate (change set) on the Agent tab, first line “Passed <head sha>: …” or “Failed <head sha>: <why>”, and QA report (change set), the report’s link. The sheet shows the gate under Staging review; a pass for an older commit reads as stale. It ends with Record agent step (record-agent-step.bpmn): the Agent tab row first, then Feedback (agent) from it, then the sheet read back, never Feedback (agent) alone. |
Set Ready for merge to YesTask_ReadyForMerge | Editor | review-sheet-script | An Editor sets the row’s Ready for merge (Orange) to Yes once the QA gate has passed for the pull request’s head commit. Person-only. Set earlier, the agent does not merge until the gate passes, and its feedback says so. |
Merge the pull requestTask_Merge | Authoring agent | review-sheet-script | The agent merges the row’s pull request, and Agentic status says merged. The change set’s Dispositions blurb, as it stands when Ready for merge is set to Yes, is the summary: it goes into the merge, and closes the change set’s issue. It ends with Record agent step (record-agent-step.bpmn): the Agent tab row first, then Feedback (agent) from it, then the sheet read back, never Feedback (agent) alone. |
Close the change set: the issue, then the sheet rowTask_CloseChangeSet | Authoring agent | review-sheet-agent-columns | Closing is one step with two tools, GitHub and the review sheet. The agent closes the change set’s issue on GitHub, with the merge or the reason it closed unmerged, then records Agentic status Closed (or Change merged) on the Agent tab through Record agent step (record-agent-step.bpmn). The sheet script then hides the row and strikes the whole row through (“make sure complete changeset rows are hidden so not cluttered and that text of that whole row is crossed out”). The agent never hides or strikes a row by hand, and never deletes one: reopening the issue and writing a new status shows it again. Hiding and striking are formatting only, which the review-log watcher ignores. A change set closed without a merge, at a person’s request, takes this step too. |
Decisions
1 of 2 decision(s) carry no documentation — gateway-documented lists them.
| decision | what decides it | branches |
|---|---|---|
Feedback changed since the proposal?Gateway_FeedbackChanged | Answered by the script, which compares the row’s Blue cells with the basis the agent wrote. changed: the proposal is marked stale and Ready for agent goes back to No, so the agent proposes again and an Editor decides again. agreed: nothing moved, and the row goes to the merge decision. | changed → Propose a direction agreed → QA gate: check dispositions and PR |
QA gate passed for the PR’s head?Gateway_QaPassed | — | failed → Edit the document in the row’s pull request passed → Set Ready for merge to Yes |