Repository navigation
Conversation
AI review: no P0-P2 findingsThis docs-only change to ⚪ P3
Not checked: The AI review read the diff, the code, and the PR's text; it ran no tests or builds and read nothing outside this repository.
Human review: needed
The AI review found no P0-P2 problems at 9e7e9af, so the code needs no second review for bugs. Decide the points above: approve to accept them, or request changes. Any collaborator with write access other than the author can approve. |
| In Merge mode, LavaFlow can restart CI once on the same pull request when a | ||
| required GitHub Actions check times out and the other checks are settled. The | ||
| new commit keeps the same changes. LavaFlow waits for GitHub's checks and any | ||
| required approvals on that commit. |
There was a problem hiding this comment.
⚪ P3: "Waits for any required approvals" conflicts with the guide's approval holds
The new sentence says LavaFlow waits for GitHub's checks "and any required approvals" on the restarted commit. Elsewhere the same page says a repository that requires an approving review holds the fix with repository_requires_approval (line 1125). It also says "An approving review on GitHub doesn't release a hold" (line 1207). Under autonomy: merge, a fix that needs approvals is therefore held and never gets a CI restart. A reader may think approving the new commit will let LavaFlow merge it. Either drop "and any required approvals", or say exactly which approval LavaFlow waits for, if the product really does wait for one.
Found by claude-opus-5-5
| New reasons may appear. | ||
|
|
||
| In Merge mode, LavaFlow can restart CI once on the same pull request when a | ||
| required GitHub Actions check times out and the other checks are settled. The |
There was a problem hiding this comment.
⚪ P3: "Times out" is ambiguous next to checks_timed_out, and the result of a second timeout isn't stated
The reason table just above defines checks_timed_out as checks that didn't all finish within 24 hours. The new paragraph says LavaFlow restarts CI when a required GitHub Actions check "times out". A reader can't tell whether this means a check GitHub concludes as timed_out or LavaFlow's 24-hour limit. They also can't tell whether a fix stopped with checks_timed_out was already retried. The paragraph also doesn't say which reason a fix gets if the restarted CI times out again. Name the GitHub conclusion, or tie the sentence to the matching table row, and state the reason the fix gets after the one retry.
Found by claude-opus-5-5
| If GitHub removes a LavaFlow pull request from the merge queue because the | ||
| merge group's checks failed, LavaFlow can queue the same pull request again | ||
| once. Its current head must still pass CI and satisfy the repository's merge | ||
| rules. A manual removal ends the watch. |
There was a problem hiding this comment.
⚪ P3: "Merge mode" and "the watch" are used nowhere else in the guide
The rest of the page calls this setting autonomy: merge (for example lines 944, 1035 and 2330), not "Merge mode". "The watch" is not defined anywhere. "A manual removal ends the watch" also doesn't give the outcome a reader would match on: the merge stops with reason removed_from_queue. The same goes for a merge group that fails again after the one requeue. Use autonomy: merge, and say that both cases stop the merge with removed_from_queue. This ties the paragraph to the rewritten table row. spec/writing.md asks for wire values quoted exactly as the API spells them.
Found by claude-opus-5-5
| | `not_mergeable` | GitHub can't merge the pull request, for example because it conflicts with its base branch. Resolve the conflict first | | ||
| | `branch_behind` | The base branch requires pull requests to be up to date with it and has no merge queue. LavaFlow doesn't update fix branches, so update the branch first | | ||
| | `removed_from_queue` | The fix isn't in the merge queue, and LavaFlow can't tell why: its checks may have failed there, or someone removed it | | ||
| | `branch_behind` | The base branch changed and the pull request still needs an update before it can merge | |
There was a problem hiding this comment.
⚪ P3: branch_behind row lost its cause and fix, and the ruleset step still says LavaFlow doesn't update fix branches
The old row named the cause: the base branch requires pull requests to be up to date and has no merge queue. It also said what to do: LavaFlow doesn't update fix branches, so update the branch first. The new row only says the base changed and the pull request needs an update. A reader who hits branch_behind no longer learns that their Require branches to be up to date setting causes it, or who has to update the branch. Step 3 of Require a status check before LavaFlow merges (lines 993-996) still says "LavaFlow doesn't update fix branches, so it stops a fix whose base branch requires that, with branch_behind". Meanwhile, the new repair paragraph says LavaFlow revises the pull request "against the current base" when there's a conflict. If LavaFlow still never updates a branch that is behind, put the cause and the "update the branch yourself" step back in the row. If repairs now update it, change step 3 to match.
Found by claude-opus-5-5
| `checks_timed_out` applies when the checks have not all finished within 24 | ||
| hours. | ||
|
|
||
| When GitHub Actions reports a failure on the current commit, or GitHub |
There was a problem hiding this comment.
⚪ P3: Repair paragraph doesn't say which fixes LavaFlow may push repairs to
The CI-restart paragraph opens with autonomy: merge, but the repair paragraph doesn't say which fixes it covers. Other parts of the page say LavaFlow never pushes to a fix you merge after its one CI start (line 910). They also say it never pushes to a held fix (line 1075) or a stopped one (line 1243). Two readers can't tell whether LavaFlow will push model-written repairs to their pull request after its CI fails: someone using open_pr, or someone with a held fix whose CI LavaFlow started once. Say the scope, for example "With autonomy: merge, while LavaFlow waits to merge a fix, …".
Found by claude-opus-5-5
| When GitHub Actions reports a failure on the current commit, or GitHub | ||
| reports a conflict with the target branch, LavaFlow can revise the same pull | ||
| request. It reviews the complete change against the current base, keeps the | ||
| last reviewed proposal if it cannot complete the repair, and allows up to |
There was a problem hiding this comment.
⚪ P3: Repair paragraph doesn't give the outcome when repairs run out or stop
"Keeps the last reviewed proposal if it cannot complete the repair" doesn't say what the reader sees. The page never defines a "proposal" in this sense. The paragraph also doesn't say which reason the merge gets after the second repair fails. It could be checks_failed for a CI failure or not_mergeable for a conflict. The events that stop the work don't match the codes the tables use. A push by someone else holds the fix with person_commits. A retarget, draft or closure stops it with handed_off, and the table says "drafted" where this paragraph says "redraft". Name the resulting reason or hold code for each case, the same way the timeout paragraph names checks_failed.
Found by claude-opus-5-5
| update fix branches, so it stops a fix whose base branch requires that, with | ||
| `branch_behind`. | ||
| the name your pull request workflow's job reports, such as `test`. If you | ||
| enable **Require branches to be up to date before merging**, LavaFlow can |
There was a problem hiding this comment.
⚪ P3: Step 3 promises branch updates, but the repair paragraph never lists a branch that is only behind as a trigger
Step 3 now says that when Require branches to be up to date before merging is on, LavaFlow "can update its own fix branch, review the updated patch, and run the checks again". The branch_behind row agrees: LavaFlow "could not complete an update". But the only paragraph that describes LavaFlow pushing to an open fix (lines 1280-1289) lists just two triggers: a GitHub Actions failure, or a conflict with the target branch. A branch that is behind but has no conflict matches neither. It also doesn't say whether such an update counts toward the "up to two repairs". A reader whose main moves often can't tell how many times LavaFlow will update the branch before it stops with branch_behind. Add "the base branch requires it to be up to date and it is behind" to the repair triggers, and say whether it counts toward the two-attempt limit.
Found by claude-opus-5-5
| `checks_timed_out` applies when the checks have not all finished within 24 | ||
| hours. | ||
|
|
||
| LavaFlow can revise an open pull request it manages under `autonomy: merge` |
There was a problem hiding this comment.
⚪ P3: The opt-in text for autonomy: merge doesn't mention that LavaFlow now pushes repairs to its open fixes
Owners decide whether to turn on merge from Merge fixes and Turn merging on. Lines 957-962 list what turning it on allows: running CI with your pull request workflows' secrets, and force-updating the fix's branch while it holds only LavaFlow's commits. The new paragraph adds model-written replacement patches, pushed to an open pull request after CI fails or the base conflicts. Each one runs CI again. It also adds branch updates when the base requires up-to-date branches. None of this appears near the opt-in, so an owner reading only that section underestimates what merge does. Add a sentence to lines 957-962 that links to the repair paragraph. Also say whether a repair goes through the same holds (human_review_paths, sensitive_path) and the Check before CI starts as the first CI start.
Found by claude-opus-5-5
| merge when the repository's requirements are met. A patch that fails review | ||
| leaves the last published proposal open with `review_unresolved`. If the | ||
| last repair's checks fail, the pull request stays open with `checks_failed`. | ||
| A push by another contributor, a retarget, a redraft, or a closure stops |
There was a problem hiding this comment.
⚪ P3: Repair stop events aren't tied to the codes the tables use, and "proposal" is undefined
Failed review and failed checks now name review_unresolved and checks_failed. The final sentence still only says that a push by someone else, a retarget, a redraft or a closure "stops automatic work". The rest of the page reports these as specific codes: another contributor's push holds the fix with person_commits, and the handed_off row covers drafted, closed or moved pull requests (it says "drafted", not "redraft"). "The last published proposal" also uses a term the page never defines; "the pull request's last reviewed commit" says the same thing in the page's own words. spec/writing.md asks for wire values quoted exactly, so name the resulting code for each event.
Found by claude-opus-5-5
| LavaFlow reviews the whole | ||
| replacement against the current base and can attempt up to two repairs on | ||
| the same pull request. It runs CI on each reviewed repair and continues to | ||
| merge when the repository's requirements are met. If a repair cannot |
There was a problem hiding this comment.
⚪ P3: Repair paragraph no longer names the reason a run gets when a repair can't continue, and cites Slack
At the previous head, this paragraph named the codes a stopped repair reports (review_unresolved, checks_failed). The new text only says the pull request stays open and that "the dashboard and Slack still show what blocks the published fix: failing checks, a conflict, or an outdated base." An API or MCP reader matching on merge.status/reason can't tell what to expect: probably checks_failed, not_mergeable or branch_behind, and maybe review_unresolved when a repair fails LavaFlow's review. The guides also never say that Slack shows merge state. lavaflow-slack.md says a run started from Slack only opens a pull request, even where the project lets LavaFlow merge, so Slack-started fixes never reach this flow. Name the resulting reason for each blocker, as the timeout paragraph does with checks_failed. Then either link to where Slack reports a fix's blocker or drop "and Slack".
Found by claude-opus-5-5
| merge when the repository's requirements are met. If a repair cannot | ||
| continue, the pull request stays open and the dashboard and Slack still | ||
| show what blocks the published fix: failing checks, a conflict, or an | ||
| outdated base. Earlier revision attempts count against the same budget. |
There was a problem hiding this comment.
⚪ P3: "Earlier revision attempts count against the same budget" doesn't say what counts toward the two repairs
The paragraph lists three triggers: an Actions failure, a conflict, and a target branch that moves so the pull request needs an update. It caps repairs at two. The closing sentence, "Earlier revision attempts count against the same budget", doesn't say what an "earlier revision attempt" is or whether a plain branch update counts as one of the two. Step 3 of the ruleset guide now invites owners to turn on Require branches to be up to date before merging. An owner whose main moves often can't tell how many base moves LavaFlow absorbs before it stops with branch_behind. State plainly whether a branch update uses up one of the two repairs.
Found by claude-opus-5-5
| LavaFlow reviews the whole replacement against the current base and can | ||
| attempt up to two repairs on the same pull request. It runs CI on each | ||
| reviewed repair and continues to merge when the repository's requirements | ||
| are met. If a repair cannot continue, the pull request stays open. The |
There was a problem hiding this comment.
⚪ P3: Recovery paragraphs don't name the reason a run ends with, and cite Slack without support
"If a repair cannot continue, the pull request stays open. The dashboard and Slack show the failing checks, conflict, or outdated base" doesn't give the merge.status/reason an API, CLI or MCP reader would match on. That is probably checks_failed, not_mergeable or branch_behind, or review_unresolved when a repair fails LavaFlow's review. The requeue paragraph has the same gap. "A manual removal stops automatic merging" doesn't say the run gets removed_from_queue, and nothing says what happens when the one requeue fails again. The guides also never say Slack shows merge state: lavaflow-slack.md (line 112) says a Slack-started run only opens a pull request. Name the resulting reason for each case, as the timeout paragraph does with checks_failed. Then either link to where Slack reports a fix's blocker, or drop "and Slack".
Found by claude-opus-5-5
| reviewed repair and continues to merge when the repository's requirements | ||
| are met. If a repair cannot continue, the pull request stays open. The | ||
| dashboard and Slack show the failing checks, conflict, or outdated base. | ||
| Earlier revision attempts count against the same budget. |
There was a problem hiding this comment.
⚪ P3: "Earlier revision attempts count against the same budget" doesn't say what counts toward the two repairs
The paragraph lists three triggers: a CI failure, a conflict, and a target branch that moves. It caps repairs at two. The closing sentence doesn't say what an "earlier revision attempt" is. The page already uses "revision" for review-round revisions (line 1983) and the pre-open checks revision (line 450). It also doesn't say whether a plain branch update uses up one of the two repairs. Step 3 of the ruleset guide invites owners to turn on Require branches to be up to date before merging. An owner whose main moves often can't tell how many base moves LavaFlow absorbs before it stops with branch_behind. State which events use up the budget.
Found by claude-opus-5-5
| LavaFlow can revise an open pull request it manages under `autonomy: merge` | ||
| when CI reports a failure on its current commit, GitHub reports a conflict, | ||
| or its target branch moves and the pull request needs an update. It can use | ||
| GitHub Actions job logs, required GitHub App check output and annotations, |
There was a problem hiding this comment.
⚪ P3: New model inputs (CI job logs, check output, status feedback) aren't covered by the page's data and redaction statements
The latest commit says repairs use GitHub Actions job logs, required GitHub App check output and annotations, and feedback published with required commit statuses. The page's data statements predate this. Line 19 says LavaFlow sends "this project's logs and source code" to an AI service. Lines 829-832 say LavaFlow redacts secrets before the models read "your logs, issue, report and a written issue's description". Neither says whether CI output and third-party check text are sent and redacted the same way. An owner deciding on autonomy: merge needs that, because CI logs can carry values GitHub doesn't mask. Say whether these sources get the same redaction, and mention them where the page says what LavaFlow sends.
Found by claude-opus-5-5
| GitHub Actions job logs, required GitHub App check output and annotations, | ||
| and feedback published with required commit statuses. | ||
|
|
||
| LavaFlow reviews the whole replacement against the current base and can |
There was a problem hiding this comment.
⚪ P3: Repair paragraph doesn't say repair commits pass the same holds and Check before CI starts
"It runs CI on each reviewed repair" means model-written replacement code runs your CI with your pull request workflows' secrets. Check before CI starts describes only the first CI start, and the path holds (path, sensitive_path, risky_change) are described for the fix as opened. Only line 2485 hints that the workflow check covers revisions. A reader can't tell whether a repair that touches CI configuration or a human_review_paths glob is held, or whether the workflow and CI-outside-Actions checks run again before each repaired commit lands. Add one sentence saying so, with a link to that section.
Found by claude-opus-5-5
| LavaFlow reviews the whole replacement against the current base and can | ||
| attempt up to two repairs on the same pull request. It runs CI on each | ||
| reviewed repair and continues to merge when the repository's requirements | ||
| are met. If a repair cannot continue, the pull request stays open. The |
There was a problem hiding this comment.
⚪ P3: Identify the merge outcome when a repair cannot continue
The paragraph says the pull request stays open, but does not map failed or exhausted repairs to merge.status and reason. The adjacent table distinguishes review_unresolved, checks_failed, not_mergeable, and branch_behind. State which outcomes apply so API and MCP readers can interpret a stopped repair.
Found by gpt-6.1-sol
| reviewed repair and continues to merge when the repository's requirements | ||
| are met. If a repair cannot continue, the pull request stays open. The | ||
| dashboard and Slack show the failing checks, conflict, or outdated base. | ||
| Earlier revision attempts count against the same budget. |
There was a problem hiding this comment.
⚪ P3: Define which revisions consume the two-repair budget
“Earlier revision attempts” is undefined. The guide also describes revisions during initial review, and this paragraph includes branch updates among repair triggers. Clarify whether those initial revisions and branch-only updates consume the same two attempts, so readers can understand how much recovery remains.
Found by gpt-6.1-sol
Document LavaFlow's one-time retry for a required Actions timeout, reviewed repairs for failures and conflicts on the same PR, and a bounded retry after a verified merge-group check failure.
This documents Kong/volcano-hosting#3532. Publish after the behavior reaches production.
Locally verified with
pnpm lint,pnpm lint:docs content/platform/guides, andpnpm build.