Triage

Triage

Move tracker issues through a small, explicit triage state machine while preserving maintainer control over external changes.

If this repo treats external pull requests as a request surface, triage covers them too: a PR is an issue with attached code — same roles, same states, same machine, with PR-specific deltas noted below. Resolve a bare #42 to an issue or PR per the tracker config.

Every comment or issue posted to a tracker during triage must start with:

> *This was generated by AI during triage.*

When to Use

Use this skill when the user wants to triage issues, review incoming bugs or feature requests, classify tracker work, prepare an issue for an AFK agent, request reporter information, close out-of-scope requests, or move issues through a triage workflow.

Use write-a-story when the user wants backlog drafting without tracker state management. Use grilling when the main task is an interview, and call it as a subroutine only when a triage issue needs more shaping. Use a debugging skill when the user asks to fully investigate and fix a bug rather than classify it.

Artifacts

• Produces: tracker state (labels, comments, status via connected tool)
• Consumes: stories at the story key path (if present) — see references/artifact-paths.md (default docs/stories/.md), .context/triage.md, .context/project.md, .context/git-workflow.md

Core Rule

Inspect and recommend freely. Before changing labels, statuses, fields, comments, descriptions, assignees, or closure state in an external tracker, show the exact intended mutation and get explicit maintainer approval.

Canonical Roles

Category roles:

• bug - something is broken.
• enhancement - new feature or improvement.

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.
• ready-for-human - needs human implementation.
• wontfix - will not be actioned.

Every triaged issue should carry exactly one category role and one state role. If state roles conflict, stop and ask the maintainer before changing anything.

State Transitions

unlabeled → needs-triage → needs-info ⟵→ needs-triage
                         → ready-for-agent
                         → ready-for-human
                         → wontfix

An unlabeled issue normally goes to needs-triage first. 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.

For a PR, the same states read against the attached code: ready-for-agent means a brief is attached and an agent should act on the diff; ready-for-human means it's ready for a human to merge.

Tracker Mapping

Treat the roles above as canonical concepts, not literal tracker labels. First look for .context/INDEX.md and .context/triage.md, then project-local mapping such as .triage/roles.md, .triage/config.md, or equivalent repository documentation. If no mapping exists, inspect existing tracker labels/statuses/fields and ask the maintainer to confirm the mapping before mutation.

Adapt to available tracker tools:

• GitLab: use glab or a GitLab MCP/API tool when available.
• GitHub: use gh or a GitHub MCP/API tool when available.
• Jira: use a connected Jira MCP/tool when available.
• Other trackers: use available tools only when they support reading issues and applying the approved mutations.

Workflow

1. Interpret the maintainer request: show attention queue, triage a specific issue, perform a quick state override, or list issues in a state.
2. Gather context. Read the issue body, comments, current roles, reporter, dates, and prior triage notes. Check .context/INDEX.md, .context/project.md, .context/git-workflow.md, .context/triage.md, project docs, relevant code paths, ADRs, and .out-of-scope/*.md when present. Run two checks: (a) redundancy — search for an existing implementation of the requested behavior by domain concept, not just the request's wording, and report where you looked; if found, it is an already-implemented wontfix (step 6). (b) prior rejection — read .out-of-scope/*.md and surface any file that resembles this request.
3. Recommend category and state with reasoning, a brief codebase or tracker-context summary, and any mapping uncertainty. Wait for maintainer direction before mutation.
4. For bugs, attempt lightweight reproduction before grilling: follow reporter steps, trace the likely code path, and run targeted commands when reasonable. Report confirmed repro, failed repro, or insufficient detail. For a PR, confirm the diff does what it claims — check it out, run relevant tests or commands.
5. If the issue needs shaping, run grilling and domain-modeling together — grill it into shape one question at a time, sharpening domain terms and updating CONTEXT.md/ADRs inline as decisions land. Preserve resolved facts in the final triage notes or brief.
6. Apply the approved outcome using available tracker tools, preserving the disclaimer on every posted tracker comment.

When showing the attention queue, present counts and one-line summaries oldest first for unlabeled issues, needs-triage issues, and needs-info issues with reporter activity since the last triage notes. When PRs are in scope, include external PRs and tag each line [PR] or [issue]. Discovery surfaces only external PRs — a collaborator's in-flight PR is not triage work. Let the maintainer pick. For quick state overrides, trust the maintainer, show the exact planned mutation, and skip grilling.

Outcomes

• ready-for-agent: post an agent brief using references/agent-brief.md.
• ready-for-human: use the same brief structure, and explain why it needs human judgment, access, design approval, or manual testing.
• needs-info: post triage notes with established facts and specific reporter questions.
• wontfix bug: post a polite explanation and close or resolve the issue.
• wontfix enhancement (rejected): update .out-of-scope/ using references/out-of-scope.md, link the record from the tracker comment, then close or resolve.
• wontfix enhancement (already implemented): point to where it lives in the codebase; do not write to .out-of-scope/ (that KB is for rejected requests, not built ones).
• needs-triage: apply the mapped role, with an optional progress comment if partial investigation was useful.

Resuming a Previous Session

If prior triage notes exist on the issue or PR, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Do not re-ask resolved questions.

Reference Map

• references/agent-brief.md: load when preparing ready-for-agent or ready-for-human handoff comments.
• references/out-of-scope.md: load when checking, writing, updating, or removing persistent rejected-enhancement records.

Review Checklist

• Is the tracker mapping known before mutation?
• Does the issue have exactly one category role and one state role?
• Has the maintainer approved external tracker changes?
• Do all posted tracker comments start with the AI triage disclaimer?
• Are resolved facts preserved so future triage does not repeat work?

Next Step

• If the maintainer approves the mutation: apply it; if the issue becomes ready-for-agent, hand off to write-a-story or the relevant implementation skill.
• If not approved: wait for maintainer direction — do not mutate tracker state (this restates the Core Rule above).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ntwrcht
• Source: ntwrcht/blvck-skills
• License: MIT

Install and usage instructions live in the source repository linked above.