gemini-cli/pr-workflow-improvements.md

PR Workflow Improvements: Lessons Learned & Skill Updates

During a recent PR review cycle, we encountered two significant workflow issues that resulted in wasted review cycles, polluted diffs, and unnecessary churn. To prevent these from recurring, we need to update our standard operating procedures, specifically within the _ux_finish-pr skill.

Problem 1: Blindspots in Fetching Reviewer Feedback

The Issue

When instructed to address reviewer feedback, the agent relied on high-level PR summaries (gh pr view) and top-level comments. It completely failed to fetch or parse inline, file-specific review comments. As a result, critical feedback (like removing unsafe type casts, fixing hardcoded arrays, and reverting specific lines of code) was ignored. Furthermore, the agent did not directly reply to the reviewer's comments to confirm resolution, leaving the reviewer in the dark.

The Solution for _ux_finish-pr

The skill must be updated to strictly mandate the retrieval and addressing of all review comments, especially inline ones.

Proposed Skill Additions:

• Mandatory Comprehensive Fetching: Require the use of gh api graphql or advanced gh pr view parsing to explicitly extract inline review comments, which are often nested inside review objects and missed by basic commands.
• Checklist Execution: Mandate that the agent enumerates every single comment from the reviewer and explicitly verifies its resolution against the codebase.
• Direct Engagement: Require the agent to use the GitHub API to post a direct reply to every addressed inline comment (e.g., "Done. Extracted to a helper.") to provide the reviewer with a clear audit trail.

---

Problem 2: Git Base-State & Branch Management Errors

The Issue

When the reviewer requested that specific configuration files be reverted to their pre-PR state to remove them from the diff, the agent executed git checkout origin/main -- <files>. Because origin/main had advanced with new commits since the PR was originally branched, this action accidentally pulled in unrelated recent changes from main. This polluted the PR's diff, causing it to include changes that had nothing to do with the feature, violating the principle of atomic commits.

The Solution for _ux_finish-pr

The skill must be updated to enforce strict Git merge-base practices when reverting or referencing the original state of a PR.

Proposed Skill Additions:

• Merge-Base Awareness: Explicitly forbid blindly checking out files from the tip of origin/main when attempting to restore a file's pre-PR state.
• Safe File Reversion Protocol: Instruct the agent to always find the true branch point using git merge-base when reverting files to strip them from a PR:

  BASE_SHA=$(git merge-base origin/main HEAD)
  git checkout $BASE_SHA -- <files_to_revert>
  

• Diff Verification: Add a mandatory validation step where the agent runs git diff origin/main...HEAD on the specific reverted files to ensure their diff is completely empty, confirming they have been successfully excised from the PR.