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.

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