Repository navigation
Conversation
AI review: no P0-P2 findingsDocs-only change to the LavaFlow, CLI deploy, CLI LavaFlow, Slack and Aikido guides. Under ⚪ 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: not needed |
| fixed reason it opened none, and a link to the run in Volcano. The run link | ||
| opens the report's project in the same environment as the Slack app and still | ||
| LavaFlow replies with the project it picked and its repository. When the | ||
| project uses Merge mode and the owner has allowed repository CI, LavaFlow |
There was a problem hiding this comment.
⚪ P3: New merge conditions use terms that match no documented setting
The new paragraph says the merge path needs "Merge mode", that "the owner has allowed repository CI", and that the change goes "to the connected branch". None of these phrases appears anywhere else in the docs. lavaflow.md uses autonomy: merge, allow_ungated_workflows or lavaflow.open_pr_ci_start, and "base branch", and spec/writing.md asks for wire values to be quoted exactly as the API spells them. A reader can't tell which setting turns this on. The rewrite also drops the old statement of what happens to Slack runs that don't qualify: a request from someone other than the owner, a non-documentation fix from a problem report, or a run started again on the report's issue. Name the exact settings, and say that runs which don't qualify stop at a pull request (person_merges).
Found by claude-opus-5-5
|
|
||
| LavaFlow links the PR while following it and replies when GitHub records the | ||
| merge or LavaFlow needs help. If it opens no PR, the thread gives a reason. | ||
| The run link opens the report's project in the same environment as the Slack app and still |
There was a problem hiding this comment.
⚪ P3: "The run link" no longer has anything to refer to
The old text said the outcome reply contains "the pull request's link, or a fixed reason it opened none, and a link to the run in Volcano". The rewrite keeps the next sentence, "The run link opens the report's project…", but drops the sentence that told readers the thread gets a run link at all. Add the run link back to the description of what LavaFlow posts, for example in the "LavaFlow links the PR while following it…" sentence.
Found by claude-opus-5-5
| request for a person to review and merge. The pull request says it proposes a | ||
| requested change, not a fix, and the run's `diagnosis.requested` is `true`. | ||
| reviewers hold anything else the change adds. Your project settings and | ||
| repository rules determine whether LavaFlow can merge. You can ask it to leave the PR as a draft or stop before merge. Asking |
There was a problem hiding this comment.
⚪ P3: How to keep a requested change from merging is unclear and has no example
The guide says you can "ask it to leave the PR as a draft or stop before merge", and then that asking it "to open a draft PR still lets LavaFlow mark it ready" (and so possibly merge it). The difference between those two phrasings is subtle, and getting it wrong means the change merges into the base branch. The section already gives an example request (@Volcano add hello.md containing "hello world"). Add a copy-paste example of a request that stops before merge, as spec/writing.md asks, and say which merge.status or hold reason the run shows when it does.
Found by claude-opus-5-5
| | `sensitive_path` | It changes another path Volcano always holds: authentication code, secret files, agent instructions, CI, dependencies or configuration; see below | | ||
| | `label` | The pull request has the `needs-human-review` label | | ||
| | `client_reported_commit` | The fix is built on a commit Volcano can't tie to a push | | ||
| | `report_admission_lost` | LavaFlow could no longer verify the Slack report's base or merge authorization. See [Slack reports](lavaflow-slack.md) | |
There was a problem hiding this comment.
⚪ P3: report_admission_lost links to a page that never explains it
The new hold-reason row sends readers to the Slack guide, but lavaflow-slack.md never mentions report_admission_lost. It also never says what "the Slack report's base or merge authorization" is or what to do when it's lost. Other rows say what to check before merging. Link to a specific anchor that explains it, or add the next step to the row, for example: the reporter's Slack connection or channel binding changed, so review and merge it yourself.
Found by claude-opus-5-5
| | `blocked_by_rules` | A rule of the repository that LavaFlow can't satisfy blocks the merge | | ||
| | `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 | | ||
| | `branch_behind` | The base moved after review and LavaFlow needs a current base for this merge. Update the branch and check the changes again | |
There was a problem hiding this comment.
⚪ P3: Reworded branch_behind row drops the cause the ruleset steps still point to
The old row said branch_behind happens when the base branch requires pull requests to be up to date and has no merge queue, because LavaFlow doesn't update fix branches. Step 3 of ### Require a status check before LavaFlow merges (lines 993-996) still tells readers to leave Require branches to be up to date before merging off for exactly that reason. The new row ("The base moved after review and LavaFlow needs a current base for this merge") applies to every fix, not only Slack ones, and no longer names the setting that triggers it. Keep the up-to-date-rule cause in the row, alongside the new Slack exact-base case, so the two passages agree.
Found by claude-opus-5-5
| LavaFlow replies with the project it picked and its repository. When the | ||
| project uses Merge mode and the owner has allowed repository CI, LavaFlow | ||
| can take the owner's requested change from Slack to the connected branch. | ||
| It reviews and revises the draft PR, marks it ready once review clears, |
There was a problem hiding this comment.
🟡 P2: Reconcile the shared draft reference with automatic Slack delivery
This flow automatically marks Slack-created drafts ready, but content/platform/guides/lavaflow.md:1647–1650 still says a draft waits for a person to mark it ready. Readers following this page's link to the run reference receive conflicting guidance and can mistake an automatically progressing PR for one awaiting manual action. Update the shared draft reference to distinguish eligible Slack drafts from drafts that require a person.
Found by gpt-6.1-sol
| reviewers hold anything else the change adds. Your project settings and | ||
| repository rules determine whether LavaFlow can merge. To stop after opening | ||
| the PR, write `@Volcano add hello.md containing "hello world". Open a PR and | ||
| leave the merge to me.` LavaFlow keeps the run at `pull_request`. To keep it |
There was a problem hiding this comment.
⚪ P3: Opt-out example names pull_request, which is not a documented run state
"LavaFlow keeps the run at pull_request" quotes a value that is not a run status (pr_open), a progress.stage, or a merge.status in lavaflow.md. spec/writing.md asks for wire values to be quoted exactly as the API spells them, so a reader can't check for this value in the run. Similarly, the draft_reason table (lavaflow.md:1650–1654) has no value for a PR kept as a draft because the reporter asked for one. Name what the run actually shows, for example status: pr_open with merge.status: held and its hold reason, and add the draft_reason a requested draft gets.
Found by claude-opus-5-5
| LavaFlow replies with the project it picked and its repository. With | ||
| [`autonomy: merge`](lavaflow.md#merge-fixes), LavaFlow can take an issue from | ||
| Slack to a merge on the project's production branch. It pins the repository | ||
| revision, reviews and revises the draft PR, and marks it ready once review |
There was a problem hiding this comment.
⚪ P3: Draft-first review flow conflicts with the progress-stage table
The new text says LavaFlow "reviews and revises the draft PR, and marks it ready once review clears", and lavaflow.md:1647 now says an initial review draft can become ready automatically. But the progress.stage table (lavaflow.md:1580) still says reviewing happens before the pull request opens ("the pull request opens after it"). The new Code Quality text (lavaflow.md:2814) also says the PR opens "once its review passes". Make the flows agree, so readers know whether a draft PR exists while review is running.
Found by claude-opus-5-5
| holds that commit. | ||
| For any other deployment, LavaFlow diagnoses from the logs alone. A fix on | ||
| a `verification: repository` commit opens only while the production branch | ||
| still holds that commit. It stays held under `client_reported_commit` until |
There was a problem hiding this comment.
⚪ P3: "Stays held … until someone verifies" implies the hold can lift
The new sentence says a fix on a verification: repository commit "stays held under client_reported_commit until someone verifies that it fixes the deployed code." Waiting and held (line 1072) says a held fix is yours for good: LavaFlow never merges, pushes to, or rebases it again. Read literally, the new wording suggests that verifying the fix lets LavaFlow continue on its own. Reword it to match, for example: "It is held under client_reported_commit: check that it fixes the deployed code, then merge it yourself."
Found by claude-opus-5-5
| to review. It never merges an Aikido fix, and it writes nothing back to | ||
| Aikido: follow the run in Volcano. | ||
| reads the issue, diagnoses it, and opens a pull request when it can fix the | ||
| problem. With `autonomy: merge`, LavaFlow follows the PR through review, |
There was a problem hiding this comment.
🟡 P2: Reconcile the remaining manual-only delivery descriptions
The introduction now promises merging under autonomy: merge, but this guide's lines 119–121 still say the run stops at a pull request whatever the project's autonomy. content/platform/guides/lavaflow.md:2920–2922 repeats that restriction, and its Slack summary at lines 2913–2915 still describes requested changes as requiring a person's review. Readers can therefore expect a manual handoff when the newly documented behavior permits automatic merging. Update these passages to distinguish open_pr from merge.
Found by gpt-6.1-sol
| [`autonomy: merge`](lavaflow.md#merge-fixes), LavaFlow can take an issue from | ||
| Slack to a merge on the project's production branch. It pins the repository | ||
| revision, reviews and revises the draft PR, and marks it ready once review | ||
| clears. It follows the required checks and approvals and merges the PR when |
There was a problem hiding this comment.
🟡 P2: Slack guide says LavaFlow waits for required approvals and merges, but the main guide holds such fixes for good
The new text says LavaFlow "follows the required checks and approvals and merges the PR when they pass." In lavaflow.md, a repository that requires an approving review holds the fix with repository_requires_approval (line 1124). A held fix is "yours for good: LavaFlow never merges" it (line 1072), and "An approving review on GitHub doesn't release a hold" (line 1206). A reader whose production branch requires reviews will expect LavaFlow to merge once they approve, but the run stays held and they have to merge it themselves. Either drop "and approvals" here, or, if the Hosting change now waits for approvals on report runs, update the repository_requires_approval row and the line 1206 sentence to match.
Found by claude-opus-5-5
| waits for a person to mark it ready; `draft_reason` says why it is one, and is | ||
| `null` otherwise. | ||
| LavaFlow, and is `null` for one opened before LavaFlow recorded it. An | ||
| initial review draft can become ready automatically when reviews pass. After |
There was a problem hiding this comment.
⚪ P3: Draft-first review flow still conflicts with "reviewers check each fix before its pull request opens"
The PR now says review often runs on an open draft PR (line 1580, this line, and lavaflow-slack.md:112). Other pages still say the PR opens only after review. ## Read the review on the pull request says "LavaFlow's AI reviewers check each fix before its pull request opens" (line 2597). Line 766 says a minor problem lets "the review … pass and the pull request opens". The rewritten Code Quality section opens the PR "once its review passes" (line 2814). The draft section also no longer says what draft_reason is while the initial review draft is still under review, now that "null otherwise" is gone. Say which runs open a draft before review, and update line 2597 (and 766) to match.
Found by claude-opus-5-5
| holds that commit. | ||
| For any other deployment, LavaFlow diagnoses from the logs alone. A fix on | ||
| a `verification: repository` commit opens only while the production branch | ||
| still holds that commit. The reason `client_reported_commit` asks you to review |
There was a problem hiding this comment.
⚪ P3: Rewritten paragraph no longer says which fix is held under client_reported_commit
The old text said which fixes were held under client_reported_commit. The new sentence, "The reason client_reported_commit asks you to review the proposal against the deployed code and merge it yourself", only describes what the reason asks of you. It never says which fix gets the reason. The reader has to infer from the hold table that a fix on a verification: repository commit is the one LavaFlow won't merge. Say it directly, for example: "LavaFlow holds such a fix with client_reported_commit: check it against the deployed code, then merge it yourself."
Found by claude-opus-5-5
| [`autonomy: merge`](lavaflow.md#merge-fixes), LavaFlow can take an issue from | ||
| Slack to a merge on the project's production branch. It pins the repository | ||
| revision, reviews and revises the draft PR, and marks it ready once review | ||
| clears. It follows the required checks and approvals and merges the PR when |
There was a problem hiding this comment.
🟡 P2: Reconcile required approvals with permanent merge holds
This says LavaFlow merges after required approvals pass, but content/platform/guides/lavaflow.md:1124 lists repository_requires_approval as a hold reason, and lines 1072–1075 and 1206–1207 say holds are permanent and GitHub approval does not release them. For repositories requiring an approving review, readers receive conflicting guidance about whether they must merge manually. Reconcile these passages and explicitly describe who merges after approval.
Found by gpt-6.1-sol
AI review: re-assess the approach@swkeever, the AI review has found P0-P2 problems in 3 rounds in a row, through c9417cd, since this PR was last marked ready for review. When each fix brings new findings, the approach is usually the problem rather than the next fix, so the AI review moved this PR back to draft, where it reviews no pushes, until you decide how to go on. Consider:
Coding agents: stop here and do not push another fix for these findings. Tell the author this PR did not converge after 3 AI review rounds, summarize the open findings and where they cluster, recommend one of the options above, and wait for the author's decision before changing the code or marking the PR ready for review. Marking the PR ready for review starts a new set of 3 rounds with a review of the current head. To accept the findings as they stand, mark it ready, and once that review finishes, add the |
| close it. | ||
| A fix waiting for required checks, GitHub approval, or the merge queue | ||
| stays with LavaFlow. Once the requirements pass, LavaFlow finishes the merge. | ||
| A fix in `waiting_for_approval` needs a required approving review on GitHub. |
There was a problem hiding this comment.
🟡 P2: New waiting_for_approval state is missing from the merge.status and progress.stage tables
The PR adds a new state: "A fix in waiting_for_approval needs a required approving review" (line 1073). It also says "An approval can resume a PR in waiting_for_approval" (line 1207), and the repository_requires_approval row now says "Current runs wait in waiting_for_approval". But the merge.status table (lines 1226–1232) still lists only waiting_for_checks, queued, merged, held and stopped, and the progress.stage table (lines 1575–1582) doesn't list it either. Neither table says new values may appear. A reader or integration that matches on merge.status for a repository that requires reviews will get a value the reference doesn't define. The CLI page's show merge-state list (content/cli/lavaflow.md:240) also doesn't list it. Add a waiting_for_approval row to the table where the API returns it, saying LavaFlow merges once a required approving review lands.
Found by claude-opus-5-5
| | `sensitive_path` | It changes another path Volcano always holds: authentication code, secret files, agent instructions, CI, dependencies or configuration; see below | | ||
| | `label` | The pull request has the `needs-human-review` label | | ||
| | `client_reported_commit` | The fix is built on a commit Volcano can't tie to a push | | ||
| | `client_reported_commit` | Volcano could not verify that the reported commit matches the deployed files | |
There was a problem hiding this comment.
🟡 P2: Narrower client_reported_commit hold contradicts the CLI page, which still holds every reported commit
The PR narrows client_reported_commit in two places. The row now reads "Volcano could not verify that the reported commit matches the deployed files". The paragraph at lines 664–667 now names the hold only for a fix on a verification: repository commit. Before, it held any fix on a reported commit. So a fix on a verification: files frontend upload is no longer held. But content/cli/lavaflow.md:188-191 still says "A fix built on a commit the deploy reported, at either verification level, is always held for a person. Only a fix on a commit that a push to the repository deployed is free of that hold." Under autonomy: merge, someone who deploys a frontend with the CLI gets opposite answers about whether LavaFlow will merge the fix without them. Update the CLI page to match the Hosting behavior, or keep the guide's wording if files commits are still held.
Found by claude-opus-5-5
|
|
||
| LavaFlow's AI reviewers check each fix before its pull request opens. The | ||
| run's `review` always has their verdict and | ||
| With initial review enabled, LavaFlow opens a draft for a Live fix and posts |
There was a problem hiding this comment.
⚪ P3: "Initial review" is presented as something enabled, but no setting or capability defines it
The new text says "With initial review enabled, LavaFlow opens a draft for a Live fix…" and "runs without initial review review the patch before opening a PR". The draft section (line 1647) refers to "an initial review draft". No setting, capability or run field called initial review appears anywhere in the docs. A reader can't tell whether their project has it, how to turn it on, or whether a PR will exist while progress.stage is reviewing. Name the capability or setting that controls it (or say which runs always get it), and fix the doubled "review review".
Found by claude-opus-5-5
| | `sensitive_path` | It changes another path Volcano always holds: authentication code, secret files, agent instructions, CI, dependencies or configuration; see below | | ||
| | `label` | The pull request has the `needs-human-review` label | | ||
| | `client_reported_commit` | The fix is built on a commit Volcano can't tie to a push | | ||
| | `client_reported_commit` | Volcano could not verify that the reported commit matches the deployed files | |
There was a problem hiding this comment.
🟡 P2: Align the CLI guide with the revised reported-commit policy
This narrows client_reported_commit to commits whose deployed files could not be verified, allowing verification: files uploads to follow merge autonomy. However, content/cli/lavaflow.md:188–192 still says reported commits at either verification level are always held. Readers configuring merge through the CLI therefore receive an incorrect promise of manual handoff for frontend uploads. Update that guide to match the revised policy.
Found by gpt-6.1-sol
| close it. | ||
| A fix waiting for required checks, GitHub approval, or the merge queue | ||
| stays with LavaFlow. Once the requirements pass, LavaFlow finishes the merge. | ||
| A fix in `waiting_for_approval` needs a required approving review on GitHub. |
There was a problem hiding this comment.
⚪ P3: Include approval waiting in the merge-status table
The new prose introduces waiting_for_approval, but the merge.status reference at lines 1226–1232 still lists only the previous five states. Add the new state and its required action so readers consulting the API table receive the complete lifecycle.
Found by gpt-6.1-sol
| Only a fix on a commit that a push to the repository deployed is free of that | ||
| hold. A fix it holds or stops is yours to review and merge on GitHub. | ||
| At autonomy `merge`, LavaFlow can merge fixes built on verified source, | ||
| including a frontend upload with [file verification](deploy.md#verification). |
There was a problem hiding this comment.
🟡 P2: CLI deploy guide still says fixes on reported commits at either verification level are held
This PR changes the CLI LavaFlow page to say LavaFlow can merge fixes built on a frontend upload with file verification, and only repository-verified uploads get the client_reported_commit hold. The platform guide's hold table now says the same. But the page this line links to, content/cli/deploy.md#verification (lines 345–349), still says: "At autonomy merge, LavaFlow holds a fix built on a reported commit, at either level, for a person to merge." Someone who deploys a frontend with the CLI and follows this link gets the opposite answer about whether LavaFlow will merge the fix without them. Update that paragraph in deploy.md to say that only verification: repository fixes are held with client_reported_commit.
Found by claude-opus-5-5
| waits for a person to mark it ready; `draft_reason` says why it is one, and is | ||
| `null` otherwise. | ||
| LavaFlow, and is `null` for one opened before LavaFlow recorded it. An | ||
| initial review draft can become ready automatically when reviews pass. |
There was a problem hiding this comment.
⚪ P3: Which runs open a draft PR before review is still unstated
The text now says reviewing happens "often on an open draft PR" (line 1581), that "an initial review draft can become ready automatically" (line 1648), and "When LavaFlow opens a draft before its review…" (line 2599). It names only Code Quality as reviewing before the PR opens. "Initial review" is still not defined anywhere, so a reader can't tell whether their run will have a PR during review. Review and merge fixes yourself (line 900) also still says that under open_pr "a fix whose review passed opens ready for review", which doesn't fit a draft opened before review. Say which runs open a draft before review (for example, every run except Code Quality, or only Slack reports), and adjust line 900 to match.
Found by claude-opus-5-5
| The thread receives a link to the run in Volcano and a link to the PR when | ||
| one opens. LavaFlow replies when GitHub records the merge or LavaFlow needs | ||
| help. If no PR opens, the thread gives a reason. | ||
| LavaFlow can follow an active report until its 10-day retention window ends. |
There was a problem hiding this comment.
⚪ P3: The guide doesn't say what happens to a PR LavaFlow is still following when the report's 10-day window ends
The new sentence says "LavaFlow can follow an active report until its 10-day retention window ends". Data and retention says the window is at most 10 days from arrival, and that "a run still waiting for a deleted report stops". Under autonomy: merge, a PR waiting for checks, approval, or the merge queue can easily outlive that window. Neither section says whether LavaFlow then stops the merge, and with which merge.status and reason or hold reason. It also doesn't say whether the PR is left for the reporter to merge. Add the run's resulting state and the next step.
Found by claude-opus-5-5
| Only a fix on a commit that a push to the repository deployed is free of that | ||
| hold. A fix it holds or stops is yours to review and merge on GitHub. | ||
| At autonomy `merge`, LavaFlow can merge fixes built on verified source, | ||
| including a frontend upload with [file verification](deploy.md#verification). |
There was a problem hiding this comment.
🟡 P2: Align the linked deploy guide with file-verified merge eligibility
This now allows automatic merging for file-verified frontend uploads, but the linked content/cli/deploy.md:345–349 still says reported commits at either verification level always require a person to merge. Readers following the verification link therefore receive opposite answers about whether their frontend fix can merge automatically. Update that reference to reserve the hold for repository-only verification.
Found by gpt-6.1-sol
| one opens. LavaFlow replies when GitHub records the merge or LavaFlow needs | ||
| help. If no PR opens, the thread gives a reason. | ||
| LavaFlow follows an active report within its retention window, at most 10 days | ||
| from the report. If the report expires before the merge, or LavaFlow loses |
There was a problem hiding this comment.
⚪ P3: Data and retention still says a run waiting on a deleted report stops, while the new text says it holds the PR
The new paragraph says that if the report expires before the merge, "the run holds the PR with report_admission_lost". Data and retention (line 253 of the same page) still says "A run still waiting for a deleted report stops". Before this PR, Slack runs never merged, so that sentence only covered reports still waiting to start. Now a run waiting on checks, approval or the merge queue can also outlive the report. A reader can take "stops" to mean merge.status: stopped. Update the retention sentence to say a PR LavaFlow is still following is held with report_admission_lost.
Found by claude-opus-5-5
|
|
||
| LavaFlow's AI reviewers check each fix before its pull request opens. The | ||
| run's `review` always has their verdict and | ||
| In environments where review on a draft PR has rolled out, LavaFlow first |
There was a problem hiding this comment.
⚪ P3: Draft-first review is gated on a rollout readers can't check, and goes by two names
The new text says LavaFlow opens a draft for Live fixes "in environments where review on a draft PR has rolled out". lavaflow-slack.md:112 says "where review on a draft PR is available". The draft section (line 1648) calls it an "initial review draft" and says draft_reason is null "during initial review". Every other rollout in these guides names a capability that GET /projects/{id}/capabilities returns, such as lavaflow.open_pr_ci_start or lavaflow.slack. This one names none, so a reader can't tell whether their run will have a PR while progress.stage is reviewing. Name the capability, or say how to tell from the run, and use one term for the feature.
Found by claude-opus-5-5
| [keep the CI skip out of your base branch](#keep-the-ci-skip-out-of-your-base-branch). | ||
|
|
||
| **Once it is available,** a fix whose review passed opens ready for review. | ||
| **Once it is available,** LavaFlow can make a fix ready after its review passes. |
There was a problem hiding this comment.
⚪ P3: Guide doesn't say whether the outside-CI check runs before LavaFlow marks a review draft ready
Review and merge fixes yourself and Check before CI starts (line 2380) say a check runs "right before a fix you merge opens". When it finds CI or previews outside GitHub Actions, the fix opens as a draft, "so only CI that GitHub Actions gates sees the fix as ready for review". With draft-first review, a Live fix opens as a draft before review, and line 900 now says LavaFlow "can make a fix ready after its review passes". Neither passage says whether that check also runs before LavaFlow marks the draft ready. Repositories with outside CI rely on that check to keep the fix a draft. State that marking a review draft ready goes through the same check, and keeps the draft (draft_reason: open_pr) when it finds a service, or say what happens instead.
Found by claude-opus-5-5
Summary
Explain how LavaFlow follows eligible runtime issues, written issues, Slack reports, Aikido findings, and Code Quality fixes through review and merge under the project's autonomy. Document Slack progress and retention, explicit draft requests, and the reasons a PR can need attention.
Publish after the Hosting change reaches production. Companion to Kong/volcano-hosting#3530 and supersedes the narrow policy description in Docs #227.
Verification