SuperAPI AI Directory

github-triage

General & other

View repository

Updated 10-16 09:44

About this skill

GitHub Issue Triage

Triage issues in the current repo using a label-based state machine. Infer the repo via git remote . All GitHub operations use gh。

AI Disclaimer

Every comment or issue posted to GitHub during triage must have the following disclaimer at the top of the comment bodymustcontain the following disclaimer, placed before any other content:

> *This was generated by AI during triage.*

Reference docs

Labels

Label Type Description
bug Category Something is broken
enhancement Category New feature or improvement
needs-triage State Maintainer needs to evaluate this issue
needs-info State Waiting on reporter for more information
ready-for-agent State Fully specified, ready for AFK agent
ready-for-human State Requires human implementation
wontfix State Will not be actioned

Every issue should have exactlyone state label andone category label. If an issue has conflicting state labels (for example, both needs-triage and ready-for-agent), first flag the conflict and ask the maintainer which state is correct before doing anything else. Give a recommendation.

State Machine

Current State Can transition to Who triggers it What happens
unlabeled needs-triage Skill (on first look) Issue needs maintainer evaluation. Skill applies label after presenting recommendation.
unlabeled ready-for-agent Maintainer (via skill) Issue is already well-specified and agent-suitable. Skill writes agent brief comment, applies label.
unlabeled ready-for-human Maintainer (via skill) Issue requires human implementation. Skill writes a brief comment summarizing the task, applies label.
unlabeled wontfix Maintainer (via skill) Issue is spam, duplicate, or out of scope. Skill closes with comment (and writes .out-of-scope/ for enhancements).
needs-triage needs-info Maintainer (via skill) Issue is underspecified. Skill posts triage notes capturing progress so far + questions for reporter.
needs-triage ready-for-agent Maintainer (via skill) Grilling session complete, agent-suitable. Skill writes agent brief comment, applies label.
needs-triage ready-for-human Maintainer (via skill) Grilling session complete, needs human. Skill writes a brief comment summarizing the task, applies label.
needs-triage wontfix Maintainer (via skill) Maintainer decides not to action. Skill closes with comment (and writes .out-of-scope/ for enhancements).
needs-info needs-triage Skill (detects reply) Reporter has replied. Skill surfaces to maintainer for re-evaluation.

Issues can only move along these transitions. The maintainer can directly override any state (see Quick State Override), but the skill should flag abnormal transitions.

Invocation

The maintainer invokes /github-triage, then describes what they want to do in natural language. The skill interprets the request and takes the corresponding action.

Example requests:

  • "Show me anything that needs my attention"
  • "Let's look at #42"
  • "Move #42 to ready-for-agent"
  • "What's ready for agents to pick up?"
  • "Are there any unlabeled issues?"

Workflow: Show What Needs Attention

When the maintainer asks for an overview, query GitHub and present a summary in three groups:

  1. Unlabeled issues — new issues with no labels at all, never triaged.
  2. needs-triage issues — the maintainer needs to evaluate or continue evaluating.
  3. needs-info issues with new activity — the reporter commented again after the last triage notes comment. Check comment timestamps to determine this.

Show the count for each group. Within each group, show oldest first (those waiting longest take priority). For each issue, show the number, title, age, and a one-line summary of the issue body.

Let the maintainer choose which issue to go deeper on.

Workflow: Triage a Specific Issue

Step 1: Gather context

Before showing anything to the maintainer:

  • Read the full issue: body, all comments, all labels, reporter, time
  • If there are prior triage notes comments, parse them to understand what has already been confirmed
  • Explore the codebase to build context: understand the domain, interfaces, and existing behavior related to the issue
  • Read .out-of-scope/*.md files, and check whether the issue matches or resembles a previously rejected concept

Step 2: Present a recommendation

Tell the maintainer:

  • Category recommendation: bug or enhancement, and explain the reasoning
  • State recommendation: where the issue should flow to, and explain the reasoning
  • If it matches a prior out-of-scope rejection, show: "This is similar to .out-of-scope/concept-name.md — we rejected this before because X. Do you still feel the same way?”
  • Briefly summarize what you found in the codebase that is relevant

Then wait for the maintainer's instructions. They may:

  • Agree and ask to apply labels → do it
  • Want to flesh it out → start a /domain-model session
  • Override with a different state → apply their choice
  • Want to discuss → continue the conversation

Step 3: Bug reproduction (bugs only)

If the issue is classified as a bug, try to reproduce it before starting a /domain-model session. This will differ across codebases, but do your best:

  • Read the reporter's reproduction steps (if any)
  • Explore the codebase to understand the relevant code paths
  • Try to reproduce the bug: run tests, execute commands, or trace the logic to confirm the reported behavior
  • If reproduction succeeds, report the findings to the maintainer: including the specific behavior observed, and which conceptual area of the code it originates from
  • If reproduction fails, report that too; the bug may depend on the environment, may already be fixed, or the report may be inaccurate
  • If the report lacks enough detail to reproduce, record this; this is a strong signal that the issue should be moved to needs-info strong signal of

Reproduction attempts affect the /domain-model session and the agent brief. Confirming the reproduction and knowing the code path makes the brief much stronger.

Step 4: /domain-model session (if needed)

If the issue still needs more details before it can be handed to an agent, interview the maintainer to establish a complete specification. Use the /domain-model skill.

Step 5: Apply the outcome

Depending on the result:

  • ready-for-agent — post an agent brief comment (see AGENT-BRIEF.md)
  • ready-for-human — post a comment summarizing the task, what was confirmed during triage, and why human implementation is needed. The structure is the same as an agent brief, but note the reasons it cannot be delegated to an agent (e.g. it requires judgment calls, external system access, design decisions, or manual testing).
  • needs-info — post triage notes containing progress so far and questions for the reporter (see Needs Info Output)
  • wontfix (bug) — post a polite comment explaining the reason, then close the issue
  • wontfix (enhancement) — write to .out-of-scope/, post a comment linking to it, then close the issue (see OUT-OF-SCOPE.md)
  • needs-triage — apply a label. If there is partial progress worth preserving, you may optionally leave a comment.

Workflow: Quick State Override

When the maintainer explicitly asks to move an issue to a certain state (e.g. "move #42 to ready-for-agent"), trust their judgment and apply the label directly.

Still show the confirmation of what is about to be done: which labels will be added/removed, whether a comment will be posted or the issue closed. But skip the /domain-model session entirely.

If moving to ready-for-agentwithout going through a /domain-model session, ask the maintainer whether to write a short agent brief comment or skip it.

Needs Info Output

When moving an issue to needs-info , post a comment capturing the interview progress and telling the reporter what is still needed:

## Triage Notes

**What we've established so far:**

- point 1
- point 2

**What we still need from you (@reporter):**

- question 1
- question 2

Put everything resolved during the /domain-model session into "established so far", without losing that work. Questions for the reporter must be specific and actionable, not vague like "please provide more info".

Resuming Previous Sessions

When triaging an issue that already has previous triage notes:

  1. Read all comments and find the previous triage notes
  2. Parse what has already been confirmed
  3. Check whether the reporter has answered the open questions
  4. Show the maintainer the updated picture: "Here's where we left off, and here's what the reporter has said since"
  5. Continue the /domain-model session from where it left off, without re-asking questions that have already been resolved