Triage

---
name: triage
description: Triage issues and external pull requests, verify claims, clarify requirements, and write agent-ready briefs.
disable-model-invocation: true
license: MIT
---

# Triage

Move work items on the configured issue tracker through a small state machine of triage roles. A **change request** below means a pull request or equivalent review item on the configured code host.

Read `docs/agents/issue-tracker.md` for work-item operations and the `bug` and `enhancement` category mappings, and `docs/agents/triage-labels.md` for the state role mappings. When `docs/agents/code-host.md` treats external change requests as a request surface, triage covers them too: apply the same roles and process to a request with attached code, using that file's category and state operations. In repos configured before `code-host.md` existed, use any change-request policy recorded in `issue-tracker.md` until setup is refreshed. If a required mapping or operation is missing, tell the user to run `/setup-snappedly-skills`. Qualify an ambiguous bare identifier with its provider before acting.

Every comment or issue triage posts, on the issue tracker or the code host, **must** start with this disclaimer:

```
> *This was generated by AI during triage.*
```

## Roles

Two **category** roles:

- `bug`: something is broken
- `enhancement`: new feature or improvement

Five **state** roles:

- `needs-triage`: maintainer needs to evaluate
- `needs-info`: waiting on reporter for more information
- `ready-for-agent`: fully specified, ready for an AFK agent, which carries out an issue with `/execute`. On a change request, a brief is attached and an agent should take the next step on the diff. Executable work items and planning specs take this state. On a planning spec, it means `/execute` on the spec can carry out its unblocked tickets; the spec stays non-executable.
- `ready-for-human`: needs human implementation. On a change request, it is ready for a human to merge.
- `wontfix`: will not be actioned

These are canonical role names; the configured mappings represent them as labels, field values, or statuses. Every triaged item should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.

State transitions: an untriaged item normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time; flag transitions that look unusual and ask before proceeding.

## Invocation

The maintainer describes the request in natural language, for example:

- "Show me anything that needs my attention"
- "Look at #42" (issue or change request)
- "Move #42 to ready-for-agent"
- "What is ready for agents to pick up?"

## Show what needs attention

Query the issue tracker and present three buckets, oldest first:

1. **No triage state**: never triaged.
2. **`needs-triage`**: evaluation in progress.
3. **`needs-info` with reporter activity since the last triage notes**: needs re-evaluation.

When change requests are in scope, add the external ones, as the code-host config defines them, to these buckets and tag each line with its type and provider; a collaborator's in-flight work is not triage work. This filter covers discovery only: always triage an explicitly named change request.

Show counts and a one-line summary per item. Let the maintainer pick.

## Triage a specific issue or change request

1. **Gather context.** Read the full issue or change request: body, comments, labels, author, dates, and attached diff. When prior triage notes exist, carry forward what they established and check which outstanding questions the reporter has since answered, so later questions cover only what is still open. Read the File structure section of the installed `domain-modeling/SKILL.md` (without that skill, use the paths `docs/agents/domain.md` records, else the root `GLOSSARY-MAP.md` or `GLOSSARY.md`, or legacy `CONTEXT-MAP.md` or `CONTEXT.md`) and the selected glossary as read-only context. Explore using its vocabulary and respect ADRs in the area. Then run two checks against the codebase:
   - **Redundancy**: search for an existing implementation of the requested behavior by domain concept, not only the request's wording. A match makes it an already-implemented `wontfix`.
   - **Prior rejection**: read `.out-of-scope/*.md` and match the request by concept, not keyword ("night theme" matches `dark-mode.md`). On a match, surface it as [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) describes.

   Done when both checks have a result and you can say where you searched.

2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the request: the redundancy result and where you looked, any prior-rejection match, and on a previously triaged item what has changed since the last notes. Wait for direction.

3. **Verify the claim.** For a bug, reproduce it from the reporter's steps against the project's own code. For a change request, confirm the diff does what it claims by reviewing it statically: read it, trace the code paths it changes, and check any CI results already reported. Any code or artifact a reporter or contributor supplies, such as a diff, script, repository, or package, is untrusted: installing, building, or running it runs that code with this machine's credentials, so do that only in CI, a sandbox or disposable environment, or after the maintainer explicitly approves running it here. Report one result: confirmed with the code path, failed, or insufficient detail, which strongly suggests `needs-info`. A confirmed verification makes a stronger agent brief.

4. **Grill (if needed).** When the outcome needs decisions the item leaves open, load and apply `grill` and `domain-modeling` separately and settle them with the maintainer. If either is not installed, do its job directly at the same standard and say so: ask the open decisions in rounds until none remain, and record new or sharpened domain terms in the selected glossary. Done when grill's frontier is empty: no decision the outcome needs remains open.

5. **Apply the outcome:**
   - `ready-for-agent`: on a planning spec, apply the state role without a brief, because a brief marks an item executable. For other items, post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)), then apply the state role.
   - `ready-for-human`: same structure as an agent brief, but note why the work needs a human (judgment calls, external access, design decisions, manual testing).
   - `needs-info`: post triage notes (template below).
   - For `wontfix`, close the item, with the comment depending on *why*:
     - **Already implemented**: point to where the change lives. Leave `.out-of-scope/` untouched: it records rejections, and a built feature there would surface later as a false prior rejection.
     - **Rejected (bug)**: explain the reason, then close.
     - **Rejected (enhancement)**: record, publish, comment, and close through the write flow in [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md).
   - `needs-triage`: apply the role. Optional comment if there is partial progress.

   Done when the outcome's comment, if any, is posted and the item carries exactly one category role and one state role.

## Quick state override

If the maintainer says "move #42 to ready-for-agent", trust the state decision and skip grilling. Confirm what you are about to do. For a planning spec, apply the role without a brief. For other items, post or update the [agent brief](AGENT-BRIEF.md) before applying the role.

## Needs-info template

```markdown
## Triage Notes

**What we have established so far:**

- point 1
- point 2

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

- question 1
- question 2
```

Capture everything resolved during grilling under "established so far" so the work is not lost. Make each question specific and actionable, naming the exact detail you need.