From eb59d9be7ae90837e2204992e69925d6286d26c6 Mon Sep 17 00:00:00 2001 From: Tyler Potter Date: Wed, 28 Oct 2026 11:31:09 -0600 Subject: [PATCH 1/2] Document the handoff from agentic feedback to human review Define contributor and agent checkpoints for handing completed agentic review to human reviewers. Require current-head review evidence, resolved feedback, and adherence to CONTRIBUTING.md. --- AGENTS.md | 43 ++++++++++++++++++++++++++++++++++++++++++- CONTRIBUTING.md | 15 +++++++++++++++ 2 files changed, 57 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 126390e477..993084d89a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Start here -Read the [contributor guide](CONTRIBUTING.md) for setup and contribution procedures. +Read and follow all guidance in [CONTRIBUTING.md](CONTRIBUTING.md). Use the [documentation map](docs/README.md) to select current SDK guidance and Foundation validation commands. Follow the module rules and validation tasks below. @@ -273,6 +273,47 @@ To inspect the events the SDK emits from the sample app, use the `android-sdk-ev - Don't edit `CHANGELOG.md` in feature PRs. It is updated only in release preparation PRs. - When preparing a release changelog: tags reflect customer impact, not change size. Internal-only changes are `[MAINTENANCE]`, not `[IMPROVEMENT]`. Follow the existing entry format: `* [TAG] Description. See [#N](link)`. +## Handoff to human review + +Follow the [contributor handoff guidance](CONTRIBUTING.md#handoff-to-human-review) +and the additional agent requirements below when checking whether to prompt the +user to add `ready-for-human-review`. Check at these checkpoints: + +- After opening a PR, pushing changes to it, or marking it ready for review. +- After replying to or resolving the remaining agentic feedback. +- When an agentic review finishes and you inspect its result. +- When the user asks about PR status or readiness for human review. + +After opening a PR, pushing changes, or marking a draft ready, agents must allow +at least five minutes for asynchronous reviews to start before assessing +eligibility. Measure from the latest of these actions and restart the grace period +if the head changes. The grace period alone does not establish eligibility. + +Prompt for the label only when all of these conditions are met: + +- At least one agentic or bot review has completed against the current PR head. No feedback is not evidence that a review occurred; a review of an older revision does not qualify. +- No observed agentic reviews remain queued or running. If an expected review has not appeared, eligibility remains unconfirmed. +- All agentic feedback has been addressed or explicitly dispositioned with evidence, each feedback item has a posted reply, and all associated review threads are resolved, including outdated threads. + +Refresh the current PR head, review activity, feedback, and thread status. Check +all pages of results; if retrieval fails or is incomplete, eligibility remains +unconfirmed. Local fixes, draft replies, or a clean bot summary alone are not +sufficient. Do not resolve unaddressed feedback solely to qualify for the label. + +If eligible and the label is absent, ask: "All agentic feedback has been addressed. +Shall I add `ready-for-human-review`?" Apply the label only after user confirmation, +then recheck the current head and eligibility immediately before labelling. If the +label is already present, do not prompt or add it again. + +If eligibility is unconfirmed, report what remains pending. If the task ends +before the grace period or reviews complete, report the deferred check; do not +claim readiness or imply that monitoring will continue without a separately +arranged follow-up. + +This instruction does not independently authorise posting replies, resolving +threads, pushing, or merging; follow the applicable approval requirements for +those actions. Carry this rule into delegated PR work and PR automations. + # Dogfooding Branch `dogfooding` is managed only through the scripts in `ci/scripts/dogfooding/`; read `ci/scripts/dogfooding/README.md` before helping with it. Never push to `dogfooding`, open a PR from a feature branch into it, or merge into it with squash or rebase: use `feature.sh`, `sync.sh` and `reset.sh`, which open the PRs. The only change made by hand is reverting a feature's dogfood merges, as described in the README's "Remove a single feature". Show the command and ask before running the scripts, since they push branches and open PRs. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4072bc6cb4..077a1fadb8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -181,6 +181,21 @@ Make sure that your code is clean and readable, that your commits are small and atomic, with a proper commit message. We tend to use [gitmoji](https://gitmoji.carloscuesta.me/), but this is not mandatory. +### Handoff to human review + +Before applying the `ready-for-human-review` label, address all agentic review +feedback or explain with evidence why a suggestion does not apply. Reply to each +feedback item and resolve its associated review thread, including outdated threads. +Check the latest PR revision, feedback, and thread status before applying the label; +local fixes, draft replies, or a clean bot summary alone are not sufficient. + +Apply the existing label once these conditions are met so reviewers know it is +their turn. If you do not have permission to label the PR, ask a maintainer to +apply it. Do not resolve un-addressed feedback solely to qualify for the label. + +The label indicates that agentic feedback has been addressed. It does not replace +human approval or required CI and merge checks. + ## Coding Conventions Our repository uses Kotlin, as it is now the recommended language for Android. From 43769eeadf6c00125c1f3ee9bc1b689165d8c56e Mon Sep 17 00:00:00 2001 From: Tyler Potter Date: Wed, 28 Oct 2026 13:55:39 -0600 Subject: [PATCH 2/2] Require completed current-head review before contributor handoff --- CONTRIBUTING.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 077a1fadb8..2f233d33be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -183,9 +183,15 @@ atomic, with a proper commit message. We tend to use ### Handoff to human review -Before applying the `ready-for-human-review` label, address all agentic review -feedback or explain with evidence why a suggestion does not apply. Reply to each -feedback item and resolve its associated review thread, including outdated threads. +Before applying the `ready-for-human-review` label, verify that at least one +agentic or bot review has completed against the current PR head and that no +agentic reviews remain queued or running. No feedback does not prove that a +review occurred, and a review of an older revision does not qualify. If an +expected review has not appeared, eligibility remains unconfirmed. + +Address all agentic review feedback or explain with evidence why a suggestion +does not apply. Reply to each feedback item and resolve its associated review +thread, including outdated threads. Check the latest PR revision, feedback, and thread status before applying the label; local fixes, draft replies, or a clean bot summary alone are not sufficient.