guided-pr-fixup

name	guided-pr-fixup
description	Performs a guided fixup of a given GitHub PR. Checks out the PR branch, retrieves CI status and review comments, reruns flaky CI checks, resolves code/compilation/test/lint failures locally, addresses review comments, verifies locally using gradlew check, and presents changes to the user for approval before pushing or responding.

Guided PR Fixup Skill

Use this skill when the user requests to fix, update, or troubleshoot a currently open GitHub Pull Request (PR) in this repository. The goal is to get the PR passing on CI and address all code review comments with supervision from the user.

---

⚠️ Important Rules & Constraints

1. NO Unapproved Pushing: Do NOT run git push or push code to GitHub unless the user gives explicit written approval in the chat.
2. NO Unapproved Comments: Do NOT post any replies, reactions, or submit review responses directly to the PR comments on GitHub unless explicitly approved by the user.
3. Kotlin Formatting Rules: All Kotlin edits must adhere to the style guide in AGENTS.md (120-char line limit, trailing commas on multi-line lists, and Apache 2.0 headers on any new files).

---

🏃 Step-by-Step Workflow

Step 1: Checkout the PR Branch

Ask the user for the PR number or URL if not already provided. Checkout the PR branch locally:

gh pr checkout <pr-number>

Step 2: Fetch and Parse PR Status

Run the parsed status check helper script to see current CI check rollup and review comments:

gh pr view <pr-number> --json statusCheckRollup,reviews | .agents/skills/guided-pr-fixup/scripts/parse_pr_status.py

Step 3: Address CI Check Failures

Review the list of checks under === CI CHECK ROLLUP ===.

1. If checks are still running (IN_PROGRESS or QUEUED), inform the user and ask if they want to wait.
2. If a check failed:
   • Extract the Run ID from the output or the detailsUrl.
   • View the logs of the failed jobs using:

     gh run view <run-id> --log-failed
     

   • Flaky or Timeout Failure: If the failure is transient (e.g. download timeouts, network flakes, gradle daemon issues), rerun the failed jobs:

     gh run rerun <run-id> --failed
     

   • Code or Test Failure: If it is a compilation error, test failure, or lint error:
     1. Locate the file and line number.
     2. Reproduce the failure locally by running the relevant gradle task, for example:
        • All checks: ./gradlew check
        • Detekt/Formatting: ./gradlew detekt
        • Run a specific test: ./gradlew :<module>:test --tests "<class_name>"
     3. Make the necessary code modifications locally to fix the compilation or logic error.

Step 4: Address Review Comments

Review the list of comments under === REVIEW COMMENTS ===.

1. For each active comment, find the file and line number.
2. Make code edits in the local workspace to resolve the reviewer's feedback.
3. Keep a checklist of which comments have been addressed. Do NOT reply on GitHub yet.

Step 5: Local Validation

Ensure everything is fully passing before asking for approval. Run:

./gradlew check

If this fails, continue fixing errors locally until it passes.

Step 6: Present Changes and Seek Approval

Once the branch is fully corrected and passes local validation:

1. Provide the user with a clear summary in chat:
   • A list of the CI failures that were fixed.
   • A list of the review comments that were addressed.
   • A summary of the local verification status.
2. Ask the user for explicit approval:
   • "Would you like me to push these changes to GitHub now?"
   • "Would you like me to resolve or reply to the PR review comments?"

---

🛠️ Helper Commands

• Checking Run Log:

  gh run view <run-id> --log
  

• Checking Current Branch Status:

  git status
  

• Git Commit: Commit changes locally with a descriptive message. Use git commit --amend or fixups if appropriate for the repository's workflow, or simply commit normally.