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

1. Use gh for all GitHub reads and writes. Infer the repository from gh repo view or git remote.
2. 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.
3. Before any mutation, show the intended label changes, comment body, and close/reopen action if any.
4. 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.*

5. 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.
6. 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

• references/AGENT-BRIEF.md - durable brief principles and template for ready-for-agent comments.

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:

1. Query open issues with gh issue list.
2. 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.
3. Sort each group oldest first.
4. Show counts and a compact row per issue: number, title, age, labels, and one-line body summary.
5. 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.

1. Read the current issue and labels.
2. Preview what will be added, removed, posted, and closed.
3. Ask for confirmation if the requested action would post a comment or close the issue.
4. 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:

1. Read all comments.
2. Extract established facts, open questions, reproduction results, and previous label decisions.
3. Check whether the reporter has answered outstanding questions.
4. Present the maintainer with what changed since the last triage note.
5. Continue from the last unresolved question instead of restarting the triage.