github-pr-triage

name	github-pr-triage
description	Triage open PR comments/reviews and associated CI/CD workflow failures using the `triage.dart` helper script and formulate an actionable plan.
key_features	["Review feedback triaging","CI log extraction","Action plan generation"]

When to use this skill

• Use this skill when asked to address review comments, pull request feedback, or debug failing CI/CD runs on a GitHub pull request in an interactive, single-pass manner.
• This skill MUST be activated when the user asks you to "look at comments on my PR", "address comments/reviews", "fix the build/checks", or provides a PR URL/branch and asks you to fix it.
• Note: For continuous autonomous iteration loops with AI code review bots (such as Gemini Code Assist), use the pr-loop skill instead, which uses this skill's triage.dart script as its underlying triage engine.

🧠 Critical Mindset: Reviewer Feedback is NOT Gospel

• Reviewers make mistakes: Do NOT assume any reviewer — whether an automated AI bot like Gemini Code Assist or a human engineer — is infallible. AI review bots frequently hallucinate syntax limitations, suggest outdated patterns, or misunderstand broader repository architecture.
• Treat Severity Badges as Unverified External Claims: Bot-generated severity tags (such as ![critical] or ![security-high]) are unverified external claims, NOT confirmed system diagnostics or compiler errors. Never blindly trust badges.
• Mandatory Pre-Edit Empirical Verification Gate: Before editing code for any reviewer comment claiming a syntax error, compilation failure, or type issue, the agent MUST run static analysis (dart analyze) on the unmodified existing codebase first.
  • If dart analyze returns 0 issues, the reviewer's claim is empirically false. The item MUST be classified as 👎 Disagree (Hallucinated Syntax/Compile Error) and NO code changes may be made for that item.
• You have the execution advantage: External reviewers inspect static code, whereas you can execute live compilers, static analyzers (dart analyze), and test suites (dart test). Always empirically test claims before accepting them.
• You are free to disagree: If a reviewer's claim is technically wrong, if their suggestion introduces compiler warnings or regressions, or if the existing code is already optimal, mark it as 👎 Disagree. Explain your technical rationale in the triage report and propose NO code changes for that item.

How to use this skill (The Workflow)

• NEVER GUESS Target PR or Branch: If the target PR number or branch is not explicitly provided by the user, and the current git workspace state is on a trunk branch (main/master), in detached HEAD state, or matches multiple open PRs, DO NOT GUESS. The agent MUST pause execution and explicitly ask the user (using ask_question or chat) to clarify which PR or branch to target before taking action.

1. Run the Triage Script: Execute the triage.dart helper script using the run_command tool. Use the --dir (or -C) option to specify the path to the target repository directory (the project you want to triage). This ensures that the underlying git and gh commands resolve to the correct repository and branch:

   dart run <path-to-github-pr-triage-skill>/bin/triage.dart --dir <path-to-target-repository>
   

   Note: If you need to target a specific PR or URL, you can also pass --pr:

   dart run <path-to-github-pr-triage-skill>/bin/triage.dart --dir <path-to-target-repository> --pr <pr-number-or-url>
   

   Save the raw stdout of this script as a new markdown artifact named raw_triage_output.md in the artifacts directory (using the write_to_file tool).

2. Verify Workspace State:

   • The script output will show the PR URL, title, branch, Remote Commit SHA, Local Commit SHA, and Sync Status (in_sync, behind_remote, ahead_of_remote, diverged, or branch_mismatch).
   • Verify that your current git branch matches the PR source branch (headRefName).
   • Check the Sync Status:
     • If Sync Status is behind_remote, pull the latest remote commits (git pull) before making changes.
     • If Sync Status is ahead_of_remote or diverged, push or sync local commits (git push).
     • Do not start making code edits while the local workspace is out of sync with the remote PR.

3. Analyze Open Comments:

   • The script lists all unresolved review threads, top-level review comments (overall review summaries), and general PR conversation comments.
   • Read the conversations carefully to understand what reviewers are requesting.
   • Focus only on unresolved or actionable comments. Ignore comments marked as resolved unless they provide necessary context.

Replying and Resolving Comments

For every addressed review thread, you MUST execute thread resolution (thread resolution is explicit, mandatory, and un-skippable).

Use the resolve subcommand in triage.dart to programmatically reply to comments and resolve threads without shell-escaping issues:

# Reply to a comment and resolve its thread:
dart run <path-to-github-pr-triage-skill>/bin/triage.dart resolve <thread_graphql_id> <comment_database_id> "<your reply body>"

# Or resolve a thread without posting a reply:
dart run <path-to-github-pr-triage-skill>/bin/triage.dart resolve <thread_graphql_id>

Constraints

• Hard CI Gate: If CI checks are running or pending, you MUST halt execution after calling ask_question in Step 4 and DO NOT proceed to Step 5 or generate pr_triage_report.md until the user responds, as pending CI results may alter the final triage plan. (Note: Bypassed ONLY IF operating within an outer orchestrator skill like pr-loop).
• CRITICAL: You MUST NOT modify files or make any code edits to address PR comments or CI failures before generating a pr_triage_report.md artifact and obtaining explicit user approval on the plan. (Note: This constraint is bypassed ONLY IF operating within an outer orchestrator skill like pr-loop with upfront user consent).
• VCS Authorization: Selecting an option in ask_question that explicitly mentions committing or pushing serves as the user's explicit permission to perform those operations for the triage fixes. Do NOT ask for permission a second time if the user selects one of those options. (Note: This constraint is bypassed ONLY IF operating within an outer orchestrator skill like pr-loop with upfront user consent).
• Sync Code Before Comments: Do not post "Done" or "Fixed" comment replies or resolve threads on GitHub while the corresponding code fixes remain uncommitted or unpushed.
• Do NOT address resolved comments unless requested.
• NO commit --amend: Modifying commit history via git commit --amend is strictly prohibited. Always create new, atomic commits.
• NO Force Pushes: Force pushing (git push -f or --force-with-lease) is strictly prohibited under any circumstances.
• Always use the triage.dart script to fetch PR information instead of manual API calls to ensure consistency and minimize context bloat.