docs(workflow): add reply and resolve step to PR feedback sweep

[amondnet]

Summary

• Add step 4 to the PR feedback sweep protocol: reply to addressed comments and resolve bot threads only
• Bot threads identified by user.type == "Bot" in the comment payload
• Human reviewer threads left unresolved — reviewer confirms and resolves themselves
• Renumber existing steps 4–6 → 5–7

Test plan

• Review WORKFLOW.md step numbering is correct (1–7)
• Verify bot identification guidance (user.type == "Bot") is clear
• Confirm gh api command examples are accurate

---

Summary by cubic

Add a reply-and-resolve step to the PR feedback sweep: after addressing a comment, reply with what changed, @mention the author (except Copilot), and resolve bot threads only (user.type == "Bot"); leave human threads open. Clarifies gh api usage (different endpoints for inline review vs top-level PR comments) and that resolving requires the GraphQL thread ID from reviewThreads.nodes[].id (not the comment ID); steps renumbered 4–6 → 5–7.

^{Written for commit fb19efb. Summary will update on new commits.}

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines the existing PR feedback sweep protocol by introducing a new, explicit step for handling comments after they have been addressed. The primary goal is to streamline the process of acknowledging resolved feedback, particularly by automating the resolution of bot-generated comments while ensuring human reviewers retain control over their own threads. This update aims to improve clarity and efficiency in the feedback loop.

Highlights

• PR Feedback Sweep Protocol Update: A new step (step 4) has been added to the PR feedback sweep protocol, focusing on how to handle addressed comments.
• Comment Resolution Distinction: The new step specifies replying to all addressed comments and resolving only bot-generated threads. Human reviewer threads are to be left unresolved for the reviewer to confirm.
• Bot Identification Guidance: Guidance is provided for identifying bot threads using user.type == "Bot" in the comment payload.
• Step Renumbering: Existing steps 4-6 have been renumbered to 5-7 to accommodate the new step.

Changelog

• WORKFLOW.md
  • Added a new step (step 4) to the 'PR Feedback Sweep Protocol' section, detailing how to reply to addressed comments and resolve bot threads.
  • Renumbered subsequent steps (originally 4-6, now 5-7) in the 'PR Feedback Sweep Protocol' section.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[gemini-code-assist]

Code Review

This pull request improves the PR feedback sweep protocol by adding a clear step for replying to and resolving comments. The new instructions for identifying and handling bot comments are a good addition.

My review includes one comment on WORKFLOW.md that points out an inconsistency between this new documentation and the existing implementation for identifying bot users. Aligning these will improve the overall robustness of the system. The changes in this PR are otherwise clear and correct.

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

_{Auto-approved: Documentation update for internal developer workflow with no impact on production code or infrastructure.}

[cubic-dev-ai]

3 issues found across 1 file

Confidence score: 3/5

• There is concrete execution risk in WORKFLOW.md: the resolveReviewThread example uses a comment id instead of a review-thread ID, which can cause agents to call the wrong API target and fail thread resolution.
• The documented bot-detection rule in WORKFLOW.md (user.type == "Bot") conflicts with the existing logic in apps/work-please/src/tracker/github.ts (login.endsWith('[bot]')), creating likely behavior drift if followed as written.
• Reply routing guidance in WORKFLOW.md is too broad (/pulls/<pr>/comments/<id>/replies), which only fits inline review comments and may break handling for top-level PR comments/review summaries.
• Pay close attention to WORKFLOW.md, apps/work-please/src/tracker/github.ts - align identifier usage, bot detection criteria, and reply endpoint scope to avoid agent misbehavior.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="WORKFLOW.md">

<violation number="1" location="WORKFLOW.md:264">
P2: The reply example is over-generalized: `/pulls/<pr>/comments/<id>/replies` only works for inline review comments, not the top-level PR comments and review summaries this sweep also requires handling.</violation>

<violation number="2" location="WORKFLOW.md:265">
P2: The bot-detection heuristic documented here (`user.type == "Bot"`) differs from the existing implementation in `apps/work-please/src/tracker/github.ts`, which uses `login.endsWith('[bot]')`. An agent following this workflow could identify a comment author as a bot (via `user.type`) that the orchestrator treats as human (because the login doesn't end with `[bot]`), or vice versa. Either align this guidance with the current `isBotLogin` heuristic or update `github.ts` to use `user.type` as well, so bot classification is consistent across the system.</violation>

<violation number="3" location="WORKFLOW.md:265">
P2: `resolveReviewThread` needs a review-thread ID, not the comment `id` from the payload, so this example points agents at the wrong identifier.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

_{Auto-approved: Documentation-only change updating the PR feedback protocol in WORKFLOW.md.}