# Triage > Triages incoming tracker issues, bug reports, and external PRs — a classification, an investigation, or an agent-ready implementation brief. Run it with /triage. - Skill: `jayden-dang/triage` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add jayden-dang/triage` - Raw SKILL.md: https://api.skillmd.com/api/skills/jayden-dang/triage/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: jayden-dang (https://skillmd.com/u/jayden-dang) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jayden-dang/triage --- # Triage Move issues through a small state machine on the repo's configured tracker. Read the tracker operations from `docs/agents/issue-tracker.md` and the label strings from `docs/agents/triage-labels.md`; if either is missing, say so and suggest `configure-repo` before continuing (you can still triage read-only in the meantime). If the tracker config says external pull requests are a request surface, they go through the same machine — **a PR is an issue with attached code**. Collaborators' in-flight PRs are not triage work; an explicitly named PR is always in scope. Every comment you post to the tracker starts with this exact line: ``` > *This was generated by AI during triage.* ``` Supporting reference: [agent-brief-template.md](agent-brief-template.md) — the brief format and its durability rules. ## The state machine Two axes; every triaged issue carries **exactly one label from each**: - **Category:** `bug` (broken behavior) or `enhancement` (new capability) - **State:** `needs-triage` → one of `needs-info` / `ready-for-agent` / `ready-for-human` / `wontfix` `needs-info` returns to `needs-triage` when the reporter replies. These are canonical role names — apply the repo's mapped label strings, never the raw role names, unless they coincide. If an issue carries conflicting state labels, flag it and ask the user before touching it. ## Scope rule Only triage issues the user did **not** produce through this skill set's own planning. Issues born agent-ready are recognizable by a marker in the body — a `Requirements covered:` section (published by `plan-tasks`) or a marker line beginning `> *This issue was drafted by AI with` (published by `publish-issues`). Running either through triage adds a second, weaker spec on top of a real one. Skip them and say why. ## Showing the queue When asked "what needs attention", query the tracker and present three buckets, oldest first, with counts and a one-line summary per item: (1) unlabeled, (2) `needs-triage`, (3) `needs-info` with reporter activity since the last triage notes. Tag lines `[issue]`/`[PR]` when PRs are in scope. Let the user pick. ## Triaging one issue 1. **Gather context.** Read the full issue — body, comments, labels, author, dates; for a PR, the diff. Read any prior triage notes so you never re-ask an answered question. Explore the relevant code using the glossary in `CONTEXT.md`. When `docs/architecture/` exists and the issue touches a spine it covers, REQUIRED SUB-SKILL: use `inspect-invariants` for the conformance read rather than judging it here. Then run two checks: - **Redundancy:** search the codebase for an existing implementation of the requested behavior — search by domain concept, not the reporter's wording. If it already exists, the outcome is an already-implemented close (step 5); collect the evidence (where it lives, how to invoke it). If nothing matches, write down the concepts you searched. - **Prior rejection:** read `.out-of-scope/*.md` and surface any concept that resembles this request — match by idea, not keyword. If one matches, tell the user what was rejected before and why, and ask whether the decision stands. If none matches, write that down too. **Done when:** both checks have a written result — the redundancy search naming either the existing implementation or the concepts searched, and the prior-rejection read naming either the matching record or that none matched. 2. **Verify the claim.** Before recommending anything, test whether the claim holds. For a bug: reproduce it from the reporter's steps. For a PR: check out the diff and run the relevant tests or commands to confirm it does what it says. Report one of: confirmed (with the code path), could not reproduce, or insufficient detail — the last is a strong `needs-info` signal. **Done when:** you have first-hand evidence, not just the reporter's word. 3. **Recommend.** Tell the user your category + state recommendation with the reasoning and the evidence from steps 1–2. If the request is ambiguous or underspecified in ways only the user can resolve — REQUIRED SUB-SKILL: use `clarify-decisions` to shape it one question at a time before locking the recommendation. Wait for the user's direction. 4. **Apply the outcome:** - `ready-for-agent` — post an agent brief built from [agent-brief-template.md](agent-brief-template.md). The brief is the contract; the original body and thread are only context. - `ready-for-human` — same brief structure, plus one line on why it cannot be delegated (judgment call, external access, design decision, manual testing). - `needs-info` — post triage notes: what has been established so far, then specific, answerable questions for the reporter (never "please provide more info"). - `wontfix` — close, and the comment depends on why: - **Already implemented:** point to where the behavior lives, with the evidence from step 1. Do **not** write to `.out-of-scope/` — that KB records rejections, and logging built features there poisons future dedup checks. - **Rejected bug:** polite explanation, close. - **Rejected enhancement:** write or update the concept's file in `.out-of-scope/` (rules below), link it from the closing comment, close. - staying `needs-triage` — apply the label; comment only if there is partial progress worth recording. **Done when:** the issue carries exactly one category and one state label and any required comment is posted. ## The `.out-of-scope/` knowledge base One file per **concept**, kebab-case (`plugin-system.md`), never one per issue — repeat requests append to the existing file's prior-request list. Each file carries: a heading naming the concept, the decision, a **durable** reason (project scope, architectural constraint, deliberate trade-off — never "no time right now", which is a deferral, not a rejection), and a `Prior requests` list linking every issue that asked. Written in plain prose a future maintainer can act on. If the user reverses a past rejection, delete or rewrite the file and triage the new issue normally. ## Direct state changes When the user names an issue and its target state ("move #42 to ready-for-agent"), that is a decision, not a triage request — it skips the investigate/prove-claim/recommend pipeline (steps 1–3), but not the guardrails: 1. State back exactly what the change is — the label edits, any comment, whether it closes — and get the user's go-ahead before touching the tracker. 2. For a jump straight to `ready-for-agent`, offer to write the brief from [agent-brief-template.md](agent-brief-template.md); an unbriefed agent-ready issue is a trap for the next agent.