Skip to content

jupes/agent-forge-harness / .agents/skills/github-triage

github-triage

Verified

Triage 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.

FileKindSize
SKILL.mdskill md9.1 KB
references/AGENT-BRIEF.mdmarkdown5.7 KB
---
name: github-triage
description: Triage 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

1. Prefer connected GitHub tools when they support the operation; otherwise use `gh`. Resolve the repository from the request or verified remote.
2. 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.
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:

```markdown
> *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](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:

```bash
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](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. Check that the instruction authorizes each proposed action; ask only for additional actions outside that scope.
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:

```markdown
> *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.

## 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.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall