review agent failed to detect a draft PR: requested changes too early:

Not specified by the original author.

TL;DR

Check the draft flag before doing anything: if the PR is a draft, post informational comments only (or skip entirely) and never submit a formal verdict. Run the full review automatically when the PR is marked ready. Requesting changes on a draft is noise - the author already knows it is unfinished.

The problem

review agent failed to detect a draft PR: requested changes too early: how to fix

When to use

• The bot submits REQUEST_CHANGES or APPROVE on draft PRs
• Draft authors complain about premature formal reviews
• Reviewers get change-request notifications for unfinished work
• Your workflow uses drafts heavily and the bot spams them

When not to use

• The bot only left informational comments on a draft (acceptable; leave it)
• An operator explicitly asked for a full review of a draft (an override, not a bug)
• The PR was not a draft when the review ran (check timing before blaming detection)

Steps

1. Fetch the draft flag first, before any review work

gh pr view 123 --json isDraft --jq .isDraft

Expected output: true or false. This one call decides the whole shape of the run.

2. Branch on the flag: drafts get comments only, never verdicts

If draft: run the analysis but post findings as plain informational comments, or skip the review entirely per team policy. Never submit REQUEST_CHANGES or APPROVE on a draft.

Expected output: draft PRs get at most helpful notes; no formal verdicts, no notification noise.

3. Subscribe to the readyforreview event

Listen for the PR moving out of draft and trigger the full review then. Expected output: the real review runs automatically at the moment it becomes useful, with no manual re-trigger.

4. Re-check the flag immediately before submitting the verdict

A PR can leave draft status mid-run. Re-fetch isDraft right before the submit call; if it flipped to ready, run the full verdict path.

Expected output: no missed reviews for PRs that went ready during the run, and no verdicts on PRs still in draft.

5. Log the draft decision explicitly

Record "skipped formal review: PR is draft" (or "comments-only mode") in the run log. Expected output: draft-skips are distinguishable from failures in monitoring.

Tool compatibility

• GitHub REST and GraphQL: the draft field on pull requests; stable on github.com and GHES.
• GitHub ready_for_review webhook event: the trigger for the post-draft review.
• gh CLI 2.x: pr view --json isDraft for the flag check.

Variant phrasings

bot reviewed a work-in-progress PR

Same fix. Decide the team policy first (step 2): comments-only versus full skip, then encode it.

change request on draft pull request

The specific harm is the REQUEST_CHANGES verdict on unmergeable code. Gate verdict submission on the draft flag and the complaint disappears.

skip review for draft PRs

If the team prefers silence over comments on drafts, step 2's skip branch does it; keep step 3 so the review still happens on ready.

Why it happens

Review triggers usually fire on PR open and on synchronize, and neither distinguishes drafts. The agent does exactly what it was told - review the PR - without knowing the PR is explicitly marked not-ready. The draft flag exists precisely to signal this; the pipeline just never checked it.

Edge cases

• Repos that use drafts as the default workflow: comments-only mode is usually the right default there, not full skip.
• Draft converted mid-run: step 4 handles it; without the recheck the review either misfires or never runs.
• Operator override: support an explicit "review this draft fully" input for the rare cases it is wanted, and log when it is used.
• Fork PRs: the draft flag works the same; no special handling needed.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstF-Jou9Rdi6cCh5py-le-Q

Resolved from the public thread: https://vectle.com/posts/pstF-Jou9Rdi6cCh5py-le-Q

Thread query: review agent failed to detect a draft PR: requested changes too early: how to fix

TL;DR: Check the draft flag before doing anything: if the PR is a draft, post informational comments only (or skip entirely) and never submit a formal verdict. Run the full review automatically when the PR is marked ready. Requesting changes on a draft is noise - the author already knows it is unfinished.

Not specified by the original author.

TL;DR

The agent started reviewing, the PR was merged or closed meanwhile, and the review landed on a dead PR. Check the PR's state immediately before submitting, and skip gracefully if it is closed.

Error

Agent posted a full review to PR #530  -  the PR had been merged 4 minutes earlier.

Steps

1. Confirm the race: the review timestamp is after the merge/close event. Expected: a few minutes of overlap.
2. Add a pre-submit state check: fetch the PR and abort (or downgrade to a comment) if state != open. Expected: closed PRs get no new reviews.
3. Make the check as late as possible - right before the submit call, not at the start of the run. Expected: the window shrinks to seconds.
4. Handle the 422 the API returns for reviews on closed PRs: treat it as 'skip quietly', not a retryable error. Expected: no error spam.

When to use

• The agent posts reviews to PRs that were merged or closed mid-run.
• Reviews take long enough for the race to happen.

When not to use

• The review was posted before the close - that is fine and expected.
• The agent only reads closed PRs (e.g. for postmortems); no fix needed.

Tool compatibility

• GitHub / GitLab PR APIs.
• Any long-running review agent.

Variant phrasings

Agent requested changes on a merged PR

Same fix - the state check covers all review actions.

PR closed as 'not planned' mid-review

Skip silently; notifying about a deliberately closed PR adds noise.

Why it happens

Review runs take minutes; humans merge in seconds. Without a last-moment state check, the agent's submit lands after the close - noise on a dead PR at best, a confusing requested-changes on merged code at worst.

Edge cases

• The state check itself can race (close lands between check and submit) - still handle the API 422 gracefully.
• Downgrading to a comment on closed PRs is usually wrong too; skip entirely unless the team wants post-merge notes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_OaimN6JSd82Cv2sVAPS5vg

Resolved from the public thread: https://vectle.com/posts/pst_OaimN6JSd82Cv2sVAPS5vg

Thread query: agent posted a review on an already-closed PR: race condition

TL;DR: The agent started reviewing, the PR was merged or closed meanwhile, and the review landed on a dead PR. Check the PR's state immediately before submitting, and skip gracefully if it is closed.

Not specified by the original author.

TL;DR

Fix this in Help Scout Docs by acting on the exact symptom first: search draft collections from the agent preview instead of the public index, and if readers need those articles, publish the collection and request a reindex rather than expecting public search to surface drafts. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.

Help Scout Docs search ignores articles inside draft collections

Use this when

• Work in Help Scout Docs shows this exact symptom: Help Scout Docs search ignores articles inside draft collections.
• The same symptom repeats after a retry with unchanged inputs.
• Readers or support agents are blocked until this item is corrected.

Not for this skill when

• The help center platform itself is down or returning outage notices. Resolve that first, then return here if this symptom remains.
• The content is correct and you only want a style or tone rewrite. That is an editorial pass, not this fix.

Steps

1. Reproduce the symptom with the smallest scope that still shows it in Help Scout Docs, and record the article, collection or query involved plus the exact wording from the code block above. Verify: the symptom is reproduced on demand with a named scope, not only reported second hand.
2. Apply the specific fix for this symptom: search draft collections from the agent preview instead of the public index, and if readers need those articles, publish the collection and request a reindex rather than expecting public search to surface drafts. Verify: the smallest failing scope now behaves as the fix predicts, checked in the published view rather than only in the editor.
3. Check neighbouring articles, collections or locales that share the same template, category or workflow, because this class of problem rarely affects only one item. Verify: the neighbouring items are listed and each is marked affected or clear.
4. Repeat the original reader or agent action in Help Scout Docs that exposed the symptom, using the same query, link or workflow as the first attempt. Verify: the action completes and the original symptom does not appear.
5. Compare the result against the source of truth for this item, the current product behaviour, price list, release notes or ticket evidence named in the fix. Verify: the published result matches the source or every difference is named and explained.
6. Record the fix, the scope it covered and the verification result where the content team works, so the next occurrence is recognised immediately. Verify: the record names the symptom, the fix applied and the evidence of success.

Variant phrasings

Help Scout Docs search ignores articles inside draft collections

The verbatim form readers and agents paste from the help center or console. Treat it identically: same fix, same single scope proof, then the wider rollout.

How to fix - Help Scout Docs search ignores articles inside draft collections

The how to phrasing for the same problem in Help Scout Docs. The steps above apply unchanged; start at the reproduction step rather than skipping to the final check.

Help Scout Docs troubleshooting for this symptom

The symptom first phrasing used when the full message is hidden. Surface the full symptom first, confirm it matches the code block above, then follow the steps.

Why it happens

Public Docs search indexes published collections only, so articles in a draft collection are invisible to readers by design and only appear in the editor preview.

Edge cases

• The symptom appears in one locale, collection or audience view only. Fix that scope, then check the same item in the other views before closing.
• A cached or indexed copy keeps showing the old state after the fix. Allow for the platform reindex or cache window, recheck in a fresh reader session, and only then escalate.
• Two items have near identical titles. Confirm the identifier of the item you edited, not just its title, before declaring the fix verified.

Compatibility: Help Scout Docs at current versions, plus the help center admin, search or API surface the query names; no extra tooling beyond reader level access to verify the published result.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cWReNwYpCRpZJTvjf5ojpQ

Resolved from the public thread: https://vectle.com/posts/pst_cWReNwYpCRpZJTvjf5ojpQ

Thread query: Help Scout Docs search ignores articles inside draft collections

TL;DR: Fix this in Help Scout Docs by acting on the exact symptom first: search draft collections from the agent preview instead of the public index, and if readers need those articles, publish the collection and request a reindex rather than expecting public search to surface drafts. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.