| name | github-triage |
| description | Triage GitHub issues through gh and a label-based state machine. Use when the user intentionally wants GitHub issue triage, incoming bug or feature review, issue workflow labels, needs-info follow-up, or ready-for-agent briefs. |
github-triage
Triage issues in the current GitHub repository using gh, issue comments, and a label-based state machine. This skill is intentionally GitHub-specific: use it when the source of truth for the workflow is GitHub Issues, not Beads.
For Agent Forge harness work, keep Beads as the local work tracker. During GitHub triage, use Beads only for harness worklog or follow-up tasks that belong in this repo; do not mirror every GitHub issue into Beads.
Hard Rules
- Use
gh for all GitHub reads and writes. Infer the repository from gh repo view or git remote.
- Do not mutate GitHub until the maintainer has approved the exact action. Mutations include labels, issue comments, issue creation, issue closure, and assignee or milestone changes.
- Before any mutation, show the intended label changes, comment body, and close/reopen action if any.
- Every GitHub issue or comment created by the agent must start with this disclaimer, before any other content:
> *This was generated by AI during triage.*
- Treat existing label conflicts as a stop condition. If an issue has more than one state label, report the conflict, recommend one state, and ask the maintainer before changing anything.
- Do not create labels automatically. If a required label is missing, tell the maintainer which label is missing and ask whether they want it created.
Reference Docs
Label Model
Each issue should have exactly one category label and exactly one state label.
| Label | Type | Meaning |
|---|
bug | Category | Something is broken |
enhancement | Category | New feature or improvement |
needs-triage | State | Maintainer needs to evaluate or continue evaluating |
needs-info | State | Waiting on reporter for more information |
ready-for-agent | State | Fully specified and suitable for an AFK agent |
ready-for-human | State | Requires human implementation or judgment |
wontfix | State | Will not be actioned |
State Machine
| Current state | Can transition to | Trigger | Result |
|---|
unlabeled | needs-triage | Agent recommendation, maintainer approves | Apply needs-triage and category if known |
unlabeled | ready-for-agent | Maintainer confirms issue is already agent-ready | Post an agent brief comment and apply labels |
unlabeled | ready-for-human | Maintainer confirms it needs human implementation | Post a brief summary comment and apply labels |
unlabeled | wontfix | Maintainer rejects as spam, duplicate, or out of scope | Post rationale, apply wontfix, and close if approved |
needs-triage | needs-info | Maintainer needs reporter input | Post triage notes and questions, then apply needs-info |
needs-triage | ready-for-agent | Triage/specification is complete and delegable | Post an agent brief comment and apply labels |
needs-triage | ready-for-human | Triage/specification is complete but not delegable | Post a human-work summary and apply labels |
needs-triage | wontfix | Maintainer decides not to action it | Post rationale, apply wontfix, and close if approved |
needs-info | needs-triage | Reporter replies with new information | Surface the update to the maintainer and recommend re-triage |
The maintainer can override the state directly. When they do, trust the direction, but still preview the mutation and flag unusual transitions.
Safe Read Commands
Use read-only commands while gathering context:
gh repo view --json owner,name,url
gh issue list --state open --json number,title,labels,createdAt,updatedAt,author,body --limit 100
gh issue view <number> --json number,title,body,labels,author,createdAt,updatedAt,comments,url,state
Use gh api for details not exposed by gh issue view, such as timeline or exact comment timestamps. Keep those calls read-only unless the maintainer has approved a mutation.
Workflow: Show What Needs Attention
When the maintainer asks for an overview:
- Query open issues with
gh issue list.
- Group issues into:
- Unlabeled issues with no labels at all.
needs-triage issues.needs-info issues where the reporter has commented after the latest triage notes comment.
- Sort each group oldest first.
- Show counts and a compact row per issue: number, title, age, labels, and one-line body summary.
- Ask which issue the maintainer wants to inspect.
For needs-info activity, read comments and compare timestamps. A reporter reply after the latest AI triage notes comment should move the issue back into the maintainer's attention queue.
Workflow: Triage a Specific Issue
1. Gather Context
Before recommending an action:
- Read the full issue body, labels, author, timestamps, and comments.
- Parse previous AI triage notes or agent briefs so prior work is not repeated.
- Explore the codebase enough to understand the domain, relevant behavior, and likely implementation surface.
- If the repository has an approved rejected-concepts or out-of-scope knowledge base, check whether the issue matches prior decisions. Do not create or update those files unless the maintainer explicitly asks and the repo allows it.
2. Present a Recommendation
Tell the maintainer:
- Recommended category label, with reasoning.
- Recommended state label, with reasoning.
- Any label conflicts or missing labels.
- Relevant codebase context discovered during exploration.
- For similar rejected concepts, summarize the prior decision and ask whether it still applies.
Then wait for direction. The maintainer may approve labels, ask for more specification, choose a different state, or decline action.
3. Attempt Bug Reproduction
For issues categorized as bug, attempt reproduction before writing an agent brief:
- Follow reporter reproduction steps when present.
- Trace the relevant code path and existing tests.
- Run focused commands or tests when they are safe and reasonable.
- Report whether reproduction succeeded, failed, or could not be attempted due to missing detail.
A successful reproduction should appear in the final agent brief. Missing reproduction details are a strong signal for needs-info.
4. Flesh Out the Specification
If the issue is not ready, interview the maintainer in a domain-model style:
- Current behavior.
- Desired behavior.
- Key interfaces or contracts.
- Edge cases and failure modes.
- Testable acceptance criteria.
- Explicit out-of-scope boundaries.
Do not re-ask questions that previous triage notes already answered.
5. Apply the Outcome
After maintainer approval:
ready-for-agent: post an agent brief using references/AGENT-BRIEF.md, then update labels.ready-for-human: post a summary using the agent brief structure, but include why the work needs a human.needs-info: post triage notes using the template below, then update labels.wontfix: post a polite rationale, apply wontfix, and close only if approved.needs-triage: apply the label and optionally comment if there is partial progress worth preserving.
When updating labels, remove the previous state label so exactly one state remains.
Workflow: Quick State Override
When the maintainer explicitly asks to move an issue to a state, do not require a full triage session.
- Read the current issue and labels.
- Preview what will be added, removed, posted, and closed.
- Ask for confirmation if the requested action would post a comment or close the issue.
- Apply the transition after approval.
If moving to ready-for-agent without a full specification session, ask whether to write a brief agent brief now or leave the issue in needs-triage until a durable brief exists.
Needs Info Comment
When moving an issue to needs-info, post a comment like:
> *This was generated by AI during triage.*
## Triage Notes
**What we've established so far:**
- Point 1
- Point 2
**What we still need from you (@reporter):**
- Specific question 1
- Specific question 2
Questions should be specific and actionable. Capture everything already established so a later session can resume without losing progress.
Resuming Previous Sessions
When an issue has existing AI triage notes or an agent brief:
- Read all comments.
- Extract established facts, open questions, reproduction results, and previous label decisions.
- Check whether the reporter has answered outstanding questions.
- Present the maintainer with what changed since the last triage note.
- Continue from the last unresolved question instead of restarting the triage.
