Generated from folio-assistant-core/processes/content/contributor-feedback.bpmn by gen-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.

BPMN diagram: Contributor feedback on a working draft

How it connects

Lanes — who acts

lanerolewhat it does here
Authoring Committeeauthoring-committeeThe people writing the document with the editor: contributors, each with their own Contributor Feedback column (Blue). They start rows, give feedback and answer the preview. They recommend; they do not set the Ready columns.
Authoring agentauthoring-agentWrites only Green cells and the Agent tab. Proposes a direction for each row, edits the document in the row’s one pull request once an Editor says so, and merges it once an Editor says so.
EditoreditorThe one lane that decides, through the Orange Ready columns, which only the people in the sheet’s EDITORS list may set. Ready for agent lets the agent edit; Ready for merge lets it merge.
QA reviewer (independent)qc-reviewerWhoever runs the QA gate: an agent session that did not write the row’s pull request, or a person. Never the authoring agent’s own session. Writes only QA gate (change set) on the Agent tab.

Steps

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

steplaneskill / sub-processwhat it does
Start a change-set row
Task_StartRow
Authoring Committeereview-sheet-scriptA 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 direction
Task_Propose
Authoring agentreview-sheet-scriptReads: 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 Yes
Task_ReadyForAgent
Editorreview-sheet-scriptAn 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 request
Task_EditInPullRequest
Authoring agentreview-sheet-scriptOne 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 answer
Task_AnswerPreview
Authoring Committeereview-sheet-scriptMembers 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 PR
Task_QaGate
QA reviewer (independent)review-sheet-scriptReads: 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 Yes
Task_ReadyForMerge
Editorreview-sheet-scriptAn 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 request
Task_Merge
Authoring agentreview-sheet-scriptThe 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 row
Task_CloseChangeSet
Authoring agentreview-sheet-agent-columnsClosing 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.

decisionwhat decides itbranches
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

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