paulund/github-triage

GitHub Issue Triage

Triage issues in the current repo using a label-based state machine. Infer the repo from git remote. Use gh for all GitHub operations.

AI Disclaimer

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

> *This was generated by AI during triage.*

Reference docs

• references/out-of-scope.md — how the .out-of-scope/ knowledge base works

Labels

These labels are the standard set across all repos. Every repo should have them. Repo-specific labels (e.g. scope:crypto, blog-post) are allowed on top but are not managed by this skill.

Category — exactly one required

| Label | Description | | --------------- | ------------------------------ | | bug | Something is broken | | feature | New capability | | chore | Maintenance, refactor, or deps | | documentation | Docs-only changes |

State — exactly one required (maps to kanban column)

| Label | Kanban Column | Description | | -------------- | -------------- | -------------------------------------- | | needs-triage | Needs Triage | New issue, maintainer to evaluate | | needs-info | Needs Info | Waiting on reporter for more detail | | planned | Planned | Fully specified, in backlog | | in-progress | In Progress | Being worked on | | in-review | In Review | PR open, awaiting merge | | wontfix | — | Rejected; issue will be closed |

Execution — required when state is planned

| Label | Description | | ------ | -------------------------------------- | | afk | Agent can ship this autonomously | | hitl | Human-in-the-loop required |

Priority — optional

| Label | Description | | ----- | ----------------------- | | p1 | Critical path | | p2 | Important | | p3 | Nice to have |

Meta — optional, can coexist with any state

| Label | Description | | --------- | ------------------------------------- | | blocked | Waiting on an external dependency | | stale | No recent activity (auto-applied) | | prd | Issue has an associated PRD |

Conflict rule: if an issue has more than one state label, flag the conflict and ask the maintainer which is correct before doing anything else. Provide a recommendation.

State Machine

States map directly to kanban board columns. The triage skill manages the early states (needs-triage → needs-info → planned). The /ship skill drives planned → in-progress → in-review → closed.

| 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 | planned | Maintainer (via skill) | Issue already well-specified. Skill applies planned + afk or hitl; writes agent brief if afk. | | unlabeled | wontfix | Maintainer (via skill) | Spam, duplicate, or out of scope. Skill closes with comment (and writes .out-of-scope/ for features). | | needs-triage | needs-info | Maintainer (via skill) | Underspecified. Skill posts triage notes with progress so far + questions for reporter. | | needs-triage | planned | Maintainer (via skill) | Triage complete. Skill applies planned + afk or hitl; writes agent brief if afk. | | needs-triage | wontfix | Maintainer (via skill) | Maintainer decides not to action. Skill closes with comment (and writes .out-of-scope/ for features). | | needs-info | needs-triage | Skill (detects reply) | Reporter has replied. Skill surfaces to maintainer for re-evaluation. | | planned | in-progress | /ship skill | Issue picked up for implementation. /ship applies label when work begins. | | in-progress | in-review | /ship skill | PR opened. /ship applies label. | | in-review | closed | /ship skill | PR merged, issue closed. |

blocked and stale are overlays — they can be added alongside any state and removed without changing the state.

An issue can only move along these transitions. The maintainer can override any state directly (see Quick State Override below), but the skill should flag if the transition is unusual.

Invocation

The user describes what they want in natural language after invoking /github-triage.

Workflow: Show What Needs Attention

When the maintainer asks for an overview, query GitHub and present a summary grouped into three buckets:

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

Display counts per group. Within each group, show issues oldest first (longest-waiting gets attention first). For each issue, show: number, title, age, and a one-line summary of the issue body.

Let the maintainer pick which issue to dive into.

Workflow: Triage a Specific Issue

Step 1: Gather context

Before presenting anything to the maintainer:

• Read the full issue: body, all comments, all labels, who reported it, when
• If there are prior triage notes comments (from previous sessions), parse them to understand what has already been established
• Explore the codebase to build context — understand the domain, relevant interfaces, and existing behavior related to the issue
• Read .out-of-scope/*.md files and check if this issue matches or is similar to a previously rejected concept

Step 2: Present a recommendation

Tell the maintainer:

• Category recommendation: bug, feature, chore, or documentation, with reasoning
• State recommendation: where this issue should go, with reasoning
• If it matches a prior out-of-scope rejection, surface that: "This is similar to .out-of-scope/concept-name.md — we rejected this before because X. Do you still feel the same way?"
• A brief summary of what you found in the codebase that's relevant

Then wait for direction before acting.

Step 3: Bug reproduction (bugs only)

If the issue is categorized as a bug, attempt to reproduce it before starting a /domain-model session. This will vary by codebase, but do your best:

• Read the reporter's reproduction steps (if provided)
• 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 what you found to the maintainer — include the specific behavior you observed and where in the code it originates
• If reproduction fails, report that too — the bug may be environment-specific, already fixed, or the report may be inaccurate
• If the report lacks enough detail to attempt reproduction, note that — this is a strong signal the issue should move to needs-info

The reproduction attempt informs the /domain-model session and the agent brief. A confirmed reproduction with a known code path makes for a much stronger brief.

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

If the issue needs to be fleshed out before it's ready for an agent, interview the maintainer to build a complete specification. Use the /domain-model skill.

Step 5: Apply the outcome

Depending on the outcome:

• planned + afk — post agent brief, apply labels
• planned + hitl — post summary + reason it needs human work, apply labels
• needs-info — post triage notes with questions
• wontfix (bug) — explain why, close
• wontfix (feature) — write to .out-of-scope/, link in comment, close
• needs-triage — apply label

Workflow: Quick State Override

When the maintainer explicitly tells you to move an issue to a specific state (e.g. "move #42 to planned + afk"), trust their judgment and apply the labels directly.

Still show a confirmation of what you're about to do: which labels will be added/removed, and whether you'll post a comment or close the issue. But skip the /domain-model session entirely.

If moving to planned + afk without a /domain-model session, ask the maintainer if they want to write a brief agent brief comment or skip it.

Needs Info Output

When moving an issue to needs-info, post a comment that captures the interview progress and tells the reporter what's needed:

## Triage Notes

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

- point 1
- point 2

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

- question 1
- question 2

Include everything resolved during the /domain-model session in "established so far" — this work should not be lost. The questions for the reporter should be specific and actionable, not vague ("please provide more info").

Resuming Previous Sessions

When triaging an issue that already has triage notes from a previous session:

1. Read all comments to find prior triage notes
2. Parse what was already established
3. Check if the reporter has answered any outstanding questions
4. Present the maintainer with an 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 stopped — do not re-ask resolved questions