From 91fbb2d008402768abe9686e8a8b84364dd32b5b Mon Sep 17 00:00:00 2001 From: Tom Thorogood <> Date: Fri, 25 Sep 2026 09:36:32 -0700 Subject: [PATCH 1/4] Add pr-triage skill documenting PR review workflow Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/skills/pr-triage/SKILL.md | 64 +++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 .github/skills/pr-triage/SKILL.md diff --git a/.github/skills/pr-triage/SKILL.md b/.github/skills/pr-triage/SKILL.md new file mode 100644 index 00000000000..117b9c405e7 --- /dev/null +++ b/.github/skills/pr-triage/SKILL.md @@ -0,0 +1,64 @@ +--- +name: pr-triage +description: Triage open pull requests in github/explore, producing a status table with CI results and merge recommendations. Use when asked to review, triage, or summarize open PRs in this repository. +--- + +# Pull Request Triage Skill + +## Goal + +Produce a table of open pull requests with CI status and a merge recommendation, following this repository's contribution rules. + +## Table format + +| PR# | Author login | PR title | CI status | Merge recommendation | Reason | +|---|---|---|---|---|---| + +- **PR#**: link to the pull request. +- **CI status**: 🟢 all checks passed, 🟡 checks still running, 🔴 any check failed. +- **Merge recommendation**: ✔️ looks good, ❌ should be closed without further comment, 🔍 needs human review. +- **Reason**: fill in for any ❌ recommendation, explaining which rule below applies. + +## Merge recommendation rules + +1. **Dependabot PRs** (`app/dependabot`): always ✔️. These are trusted dependency bumps. +2. **`github-actions[bot]` automation PRs** (e.g. the collections-renames autofix bot): always ✔️. These are generated by repository-owned workflows, not external submissions. +3. **`github-security-bot`**: always ✔️. This is an internal, repository-owned bot, not an external contributor. +4. **PRs editing core repository metadata** (workflows, CI config, `Gemfile`, docs, etc. — anything outside `topics/` or `collections/`) submitted by an external contributor: ❌. This repository only accepts topic/collection contributions from the community; infrastructure changes need maintainer review through other channels. +5. **PRs that add or edit a topic or collection**: + - Check the PR description against `.github/PULL_REQUEST_TEMPLATE.md`. If the required checkboxes for the selected contribution type are not checked, recommend ❌ — per `CONTRIBUTING.md`, incomplete templates are closed without comment. + - If the checkboxes are complete but the contribution reads as self-promotion (e.g. the author is adding their own repository to a topic or collection), recommend ❌ citing the "Avoid conflicts of interest" guideline in `CONTRIBUTING.md`. + - If the checkboxes are complete, the change is substantive, and it isn't self-promotion, recommend ✔️. + - If CI is failing (🔴) for a PR that otherwise looks acceptable, or the contribution's value is ambiguous, recommend 🔍 for human review rather than guessing. + +## Workflow + +1. List open PRs with `gh pr list` including CI status (`statusCheckRollup`). +2. For each PR, read its body/checkboxes, diff, and any bot triage comments (e.g. the maintainer triage comment posted by `explore-triage-commenter`). +3. Apply the rules above to assign CI status and merge recommendation. +4. Present the table. Do not take merge/close actions unless explicitly asked. + +## Updating PR branches + +When asked to update PRs from the base branch, use `gh pr update-branch ` for each open PR. Dependabot, `github-actions[bot]`, and `github-security-bot` PRs are still valid targets for this — being "always accepted" for merge doesn't exempt them from branch updates. + +## CI check approval + +Workflow runs that require manual approval (e.g. first-time contributors) can be approved with: + +``` +gh api -X POST repos/github/explore/actions/runs//approve +``` + +Only do this for runs actually in `action_required` or `waiting` status — a 🔴 CI status from a completed, non-blocked run is a real failure, not a pending approval. + +## Diagnosing CI failures + +Before recommending a fix, distinguish between: + +- **A data problem**: the failure stems from stale or inconsistent content already in `main` (e.g. a topic still aliasing another topic that has since been split out on its own). Note this in the analysis; the failing PR may not be at fault, and a separate PR may already fix the underlying data. +- **A logic problem**: the failure stems from the test/workflow logic itself not accounting for a valid case (e.g. a CI job not exempting an automation bot's own PRs from a check designed for external submissions). + +## Tone + +This repository is public. Keep all analysis, PR descriptions, and comments matter-of-fact and welcoming toward external contributors — describe issues neutrally (e.g. "the description doesn't check the required boxes") rather than in dismissive or judgmental language. From c04fddee1250e4f0237b6a27189cd9c583bd39c3 Mon Sep 17 00:00:00 2001 From: Tom Thorogood <> Date: Fri, 25 Sep 2026 09:38:46 -0700 Subject: [PATCH 2/4] Prioritize blocking PRs before triage table generation Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/skills/pr-triage/SKILL.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/.github/skills/pr-triage/SKILL.md b/.github/skills/pr-triage/SKILL.md index 117b9c405e7..cd337ea2f08 100644 --- a/.github/skills/pr-triage/SKILL.md +++ b/.github/skills/pr-triage/SKILL.md @@ -33,10 +33,17 @@ Produce a table of open pull requests with CI status and a merge recommendation, ## Workflow -1. List open PRs with `gh pr list` including CI status (`statusCheckRollup`). -2. For each PR, read its body/checkboxes, diff, and any bot triage comments (e.g. the maintainer triage comment posted by `explore-triage-commenter`). -3. Apply the rules above to assign CI status and merge recommendation. -4. Present the table. Do not take merge/close actions unless explicitly asked. +Resolve PRs in this order before generating the final table, since earlier PRs can block or affect CI for the rest: + +1. **Autofix PRs** (e.g. the `github-actions[bot]` collections-renames PR). These often correct data that other PRs' CI depends on, so merge them first. +2. **Dependabot PRs** (`app/dependabot`). +3. **Other `github-*`-login-submitted PRs** (e.g. `github-security-bot`). + +Merge each blocking PR once its own CI passes, following the merge recommendation rules above. Only proceed to the next step once all blocking PRs are merged. + +4. Once all blocking PRs are merged, update every remaining open PR from the base branch (see below) to trigger fresh CI runs that reflect the newly merged fixes. +5. Only after that, list open PRs with `gh pr list` including CI status (`statusCheckRollup`), read each PR's body/checkboxes, diff, and any bot triage comments (e.g. the maintainer triage comment posted by `explore-triage-commenter`), apply the merge recommendation rules, and present the table. +6. Do not take merge/close actions on non-blocking PRs unless explicitly asked. ## Updating PR branches From fc9415a2396393f28336a986d5a811958dd07a28 Mon Sep 17 00:00:00 2001 From: Tom Thorogood <> Date: Fri, 25 Sep 2026 11:12:31 -0700 Subject: [PATCH 3/4] Check for extenuating explanation before rejecting self-promotion PRs Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/skills/pr-triage/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/skills/pr-triage/SKILL.md b/.github/skills/pr-triage/SKILL.md index cd337ea2f08..5996043ea05 100644 --- a/.github/skills/pr-triage/SKILL.md +++ b/.github/skills/pr-triage/SKILL.md @@ -27,7 +27,7 @@ Produce a table of open pull requests with CI status and a merge recommendation, 4. **PRs editing core repository metadata** (workflows, CI config, `Gemfile`, docs, etc. — anything outside `topics/` or `collections/`) submitted by an external contributor: ❌. This repository only accepts topic/collection contributions from the community; infrastructure changes need maintainer review through other channels. 5. **PRs that add or edit a topic or collection**: - Check the PR description against `.github/PULL_REQUEST_TEMPLATE.md`. If the required checkboxes for the selected contribution type are not checked, recommend ❌ — per `CONTRIBUTING.md`, incomplete templates are closed without comment. - - If the checkboxes are complete but the contribution reads as self-promotion (e.g. the author is adding their own repository to a topic or collection), recommend ❌ citing the "Avoid conflicts of interest" guideline in `CONTRIBUTING.md`. + - If the checkboxes are complete but the contribution reads as self-promotion (e.g. the author is adding their own repository to a topic or collection), check the PR description and comments for a disclosed, extenuating explanation (e.g. independent evidence of community adoption, or a maintainer acknowledgment) that might justify an exception. Absent such justification, recommend ❌ citing the "Avoid conflicts of interest" guideline in `CONTRIBUTING.md`. - If the checkboxes are complete, the change is substantive, and it isn't self-promotion, recommend ✔️. - If CI is failing (🔴) for a PR that otherwise looks acceptable, or the contribution's value is ambiguous, recommend 🔍 for human review rather than guessing. From 77452ccf893311350e29f1fbb41d4d0c2ed7ec92 Mon Sep 17 00:00:00 2001 From: Tom Thorogood <> Date: Fri, 25 Sep 2026 15:45:59 -0700 Subject: [PATCH 4/4] Require explicit user request before any PR approval, merge, or close Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/skills/pr-triage/SKILL.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/skills/pr-triage/SKILL.md b/.github/skills/pr-triage/SKILL.md index 5996043ea05..319a997712e 100644 --- a/.github/skills/pr-triage/SKILL.md +++ b/.github/skills/pr-triage/SKILL.md @@ -33,17 +33,19 @@ Produce a table of open pull requests with CI status and a merge recommendation, ## Workflow -Resolve PRs in this order before generating the final table, since earlier PRs can block or affect CI for the rest: +**Never approve, merge, or close a PR automatically. Every approval, merge, and close is a separate action the user must explicitly request, one at a time, regardless of the recommendation in the table.** This skill only produces recommendations and takes the read-only/branch-update actions described below on its own. -1. **Autofix PRs** (e.g. the `github-actions[bot]` collections-renames PR). These often correct data that other PRs' CI depends on, so merge them first. +For prioritizing which PRs matter most when the user does ask for merges, note that these often correct data that other PRs' CI depends on, so they're worth flagging as high priority in that order: + +1. **Autofix PRs** (e.g. the `github-actions[bot]` collections-renames PR). 2. **Dependabot PRs** (`app/dependabot`). 3. **Other `github-*`-login-submitted PRs** (e.g. `github-security-bot`). -Merge each blocking PR once its own CI passes, following the merge recommendation rules above. Only proceed to the next step once all blocking PRs are merged. +Steps to actually perform without being asked: -4. Once all blocking PRs are merged, update every remaining open PR from the base branch (see below) to trigger fresh CI runs that reflect the newly merged fixes. -5. Only after that, list open PRs with `gh pr list` including CI status (`statusCheckRollup`), read each PR's body/checkboxes, diff, and any bot triage comments (e.g. the maintainer triage comment posted by `explore-triage-commenter`), apply the merge recommendation rules, and present the table. -6. Do not take merge/close actions on non-blocking PRs unless explicitly asked. +1. Update every open PR from the base branch (see below) to trigger fresh CI runs. +2. List open PRs with `gh pr list` including CI status (`statusCheckRollup`), read each PR's body/checkboxes, diff, and any bot triage comments (e.g. the maintainer triage comment posted by `explore-triage-commenter`), apply the merge recommendation rules, and present the table. +3. Do not approve, merge, or close any PR — including ones recommended ✔️ or ❌ — without the user explicitly asking for that specific PR. ## Updating PR branches @@ -57,7 +59,7 @@ Workflow runs that require manual approval (e.g. first-time contributors) can be gh api -X POST repos/github/explore/actions/runs//approve ``` -Only do this for runs actually in `action_required` or `waiting` status — a 🔴 CI status from a completed, non-blocked run is a real failure, not a pending approval. +Only do this for runs actually in `action_required` or `waiting` status — a 🔴 CI status from a completed, non-blocked run is a real failure, not a pending approval. As with PR approvals and merges, only approve a workflow run to unblock CI when the user has explicitly asked for that PR to move forward. ## Diagnosing CI failures