From d60d7697f064b17312bfb70eeac870d24eda6773 Mon Sep 17 00:00:00 2001 From: bdbch Date: Thu, 22 Oct 2026 21:32:30 +0200 Subject: [PATCH] Add /maintainer-triage --- skills/maintainer-triage/SKILL.md | 146 ++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 skills/maintainer-triage/SKILL.md diff --git a/skills/maintainer-triage/SKILL.md b/skills/maintainer-triage/SKILL.md new file mode 100644 index 0000000..11ad66b --- /dev/null +++ b/skills/maintainer-triage/SKILL.md @@ -0,0 +1,146 @@ +--- +name: maintainer-triage +description: Sweep a repository's untriaged issues in one pass — classify, label, ask for missing information, close the invalid, and report the queue. Use when the maintainer asks to triage new issues, clear the issue backlog, or see what needs attention. +disable-model-invocation: true +--- + +# Maintainer Triage + +Batch triage for a repository's incoming issues. The `triage` skill moves one issue through a state machine with the maintainer in the loop; this skill clears the queue: it reads every untriaged issue, judges it against the same vocabulary, proposes an action for each, and executes the approved plan. + +Default to read-only until the maintainer approves the plan. + +## 1. Establish the ground truth + +```sh +gh auth status +gh repo view --json nameWithOwner -q .nameWithOwner +gh label list --limit 200 +``` + +Read what the repo already says about incoming work: + +- `CONTRIBUTING.md`, `GOVERNANCE.md`, `CODE_OF_CONDUCT.md` +- `.github/ISSUE_TEMPLATE/` — what a complete report looks like here +- Triage notes in `AGENTS.md`, `CLAUDE.md`, or `docs/` +- `.out-of-scope/`, if present — prior rejections + +Map the repo's labels to the canonical roles below. Never invent a label: use `gh label list`, and if a role has no label, say so instead of creating one. + +| Role | Kind | Meaning | +| --- | --- | --- | +| `bug` | category | something is broken | +| `enhancement` | category | new feature or improvement | +| `needs-triage` | state | maintainer must evaluate | +| `needs-info` | state | waiting on the reporter | +| `ready-for-agent` | state | fully specified, delegable | +| `ready-for-human` | state | needs human judgment or access | +| `wontfix` | state | will not be actioned | + +## 2. Find the queue + +```sh +# Never triaged: no labels at all. +gh issue list --state open --search "no:label sort:created-asc" --limit 100 + +# Explicitly parked. +gh issue list --state open --label needs-triage --limit 100 + +# Parked, but the reporter may have replied since. +gh issue list --state open --label needs-info --limit 100 +``` + +Filter what is not triage work, and list it rather than dropping it silently: + +- Bots: `dependabot[bot]`, `renovate[bot]`, release and CI bots. +- The maintainer's own issues, unless asked. +- Draft PRs. + +Read the full thread, never the list row: + +```sh +gh issue view --json title,body,state,author,labels,createdAt,comments +gh api repos/OWNER/REPO/issues//comments --paginate +gh api repos/OWNER/REPO/issues//timeline --paginate +``` + +## 3. Judge each issue + +Run every check and record the result for the report. + +1. **Complete?** Does it follow the repo's template: what happened, what was expected, steps, versions, environment? A bug without a reproduction is `needs-info`, not a guess. +2. **Duplicate?** Search by behaviour, not wording: + + ```sh + gh search issues --repo OWNER/REPO "" --state all --limit 20 + gh search prs --repo OWNER/REPO "" --state all --limit 20 + ``` + +3. **Already implemented?** Search the codebase for the behaviour described. If it exists, the issue is `wontfix` (already done), and the reply points at where it lives. +4. **Prior rejection?** Check `.out-of-scope/` and closed `wontfix` issues for the same request. +5. **Actionable?** Could a contributor start today without asking a question? If not, it is `needs-info` or `needs-triage`, never `ready-for-*`. +6. **Spam or abuse?** Off-topic, advertising, or hostile: flag it for the maintainer. Do not engage. + +Recommend exactly one category and one state per issue. + +## 4. Present the plan + +One table, oldest first, no writes yet: + +| # | Title | Author | Category | State | Action | +| --- | --- | --- | --- | --- | --- | + +Then a short line per issue for the action itself: labels, comment, close, assign. Keep the batch to ten issues per approval; a bigger queue gets a second round. + +Ask the maintainer to approve, amend, or skip rows. Wait. + +## 5. Execute + +Apply only what was approved, one issue at a time, so a failure stays isolated: + +```sh +gh issue edit --add-label bug --add-label needs-info +gh issue comment --body-file comment.md +gh issue close --reason "not planned" --comment "..." +``` + +For `needs-info`, use the repo's own phrasing if it has one. Otherwise: + +```markdown +## Triage Notes + +**What we've established so far:** + +- + +**What we still need from you (@reporter):** + +- +``` + +Rules for replies: + +- Specific questions only. "Please provide more info" is not triage. +- For a duplicate, link the canonical issue and close. +- For `wontfix`, say why in one or two sentences and point at the alternative if there is one. +- Never close a first-time contributor's issue without a reason in the comment. + +## 6. Report + +End with counts and the next step: + +``` +Triaged 12: 4 ready-for-agent, 5 needs-info, 2 wontfix, 1 duplicate. +Waiting on maintainer: 3 (judgment calls listed below). +Next queue: 7 issues still unlabeled. +``` + +List what you skipped and why: bots, the maintainer's own issues, anything too ambiguous to judge. + +## Guardrails + +- Read the whole thread before judging. Titles lie. +- Never mass-close or mass-label without an approved plan. +- Do not answer support questions here; route them. +- Do not create labels, milestones, or projects. +- If rate-limited, stop and report where you stopped. -- knotmirror 0.0.1