jupes/agent-forge-harness / .agents/skills/github-triage
github-triage
VerifiedTriage GitHub Issues using workflow labels and durable agent briefs. Use for GitHub issue review or reporter follow-up; use qa or triage-issue for Beads.
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
- Prefer connected GitHub tools when they support the operation; otherwise use
gh. Resolve the repository from the request or verified remote. - Apply only authorized GitHub changes. Existing explicit direction counts as approval; request missing authority after preparing the concrete change. Posting comments requires explicit messaging authorization.
- 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
- references/AGENT-BRIEF.md - durable brief principles and template for
ready-for-agentcomments.
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-triageissues.needs-infoissues 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, applywontfix, 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.
- Check that the instruction authorizes each proposed action; ask only for additional actions outside that scope.
- 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.
Completion
Every requested issue is reviewed, changed with authorization, or waiting on a named input. Re-read changed issues to verify state, labels, and authorized comments.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |