triage

A prompt or brief naming this skill is its invocation.

Triage

Move issues on the project issue tracker through a small state machine of triage roles, and bring each request you triage to an agent brief that holds.

If this repo treats external pull requests as a request surface (see the issue-tracker config), triage covers them too: a PR is an issue with attached code, using the same roles, same states, and same machine, with a few deltas marked "for a PR" below. Resolve a bare #42 to an issue or PR per the tracker config.

Start every comment or issue body you post to the issue tracker during triage with the triage disclaimer from CONTRIBUTING.md's account policy, Agents on the maintainer's account:

> *This was generated by AI during triage.*

The contribution guide's Triage and Readiness sections and the installed rules decide routing, acceptance, readiness, model labels, and owner questions. This skill is how to carry them out.

Follow AGENTS.md's Agent skills requirements for delegation and session naming. Use the available naming capability separately from the command and task context. For each research run below, apply that rule to its research task and use the listed issue references and deliverables as task context.

Reference docs

• AGENT-BRIEF.md: how to write durable agent briefs and the triage notes after them
• OUT-OF-SCOPE.md: how the .out-of-scope/ knowledge base works

Roles

Two category roles:

• bug: something is broken
• enhancement: new feature or improvement

Five state roles:

• needs-triage: maintainer needs to evaluate
• needs-info: information is missing; you, the orchestrating agent, answer it or route it (see Route questions)
• ready-for-agent: fully specified, ready for an AFK agent
• ready-for-human: needs the owner's own accounts or credentials, or a taste call the owner reserved for themselves
• wontfix: will not be actioned

For a PR, the same states read against the attached code: ready-for-agent means a brief is attached and an agent should take the next step on the diff; ready-for-human keeps the owner-only meaning above. Work an agent can perform stays ready-for-agent, including work awaiting the owner's review. In repositories with installed factory rules, follow those rules for work the factory must not pick up.

Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.

These are canonical role names. The actual label strings and their meanings are in the triage label configuration, docs/agents/triage-labels.md.

State transitions: an unlabeled issue 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 missing information arrives: your own answer, the reporter's reply, or the owner's decision. The maintainer can override at any time; flag transitions that look unusual and ask before proceeding.

Who does what

• You, the orchestrating agent: the session the maintainer invoked. You sort each request, start its research run, receive every question first, answer the intent questions you can cite, send the rest to a grill with the owner, keep the decision inbox, review each brief as if a stranger wrote it, and accept a brief that holds. You never write a brief you accept. When the owner runs triage themselves, they are the orchestrating agent.
• The research run: a sub-agent you start for one request, with a fresh context. It gathers facts and verifies the claim, then writes the brief once no intent question is open, unless a grill drafts it. Leave readiness, labels, and the judgment of its brief to yourself.
• The grill: a grilling session with the owner, in its own session, for intent questions you cannot infer. It records the owner's decisions and drafts the briefs; it files no issue and applies no readiness.
• The owner: holds the project's intent. Questions for the owner reach them only through your decision inbox, or in a grill they join. Leave readiness to them only when you cannot apply it; never ask them to finish a brief.

If you cannot start a sub-agent, do the research yourself, post the brief, and stop: tell the owner, with a link, that the brief still needs a reviewer who did not write it.

Invocation

The maintainer invokes /triage and describes what they want in natural language. Interpret the request and act. Examples:

• "Show me anything that needs my attention"
• "Let's look at #42" (issue or PR)
• "Move #42 to ready-for-agent"
• "What's ready for agents to pick up?"

Show what needs attention

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

1. Unlabeled: never triaged.
2. needs-triage: evaluation in progress.
3. needs-info with reporter activity or an owner decision since the last triage notes: needs re-evaluation.

When PRs are in scope, include external PRs in these buckets and tag each line [PR] or [issue]. Discovery surfaces only external PRs (the tracker config defines who counts as external), so a collaborator's in-flight PR is not triage work. This filter is discovery-only; an explicitly named PR is always triaged regardless of author.

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

Sort by uncertainty

Before any research, decide where the answer to the request's open questions lives. The category label does not decide it.

• Code-bound: the expected result is clear, and the code, logs, or a reproduction can answer everything else. A bug whose report or documentation states what should happen is usually code-bound.
• Intent-bound: the missing answer is the owner's intent, a policy, or a trade-off only they can choose: a new capability, a "should" question, a limit, a default, a timeout, a naming or scope call.

The test: if the brief would have to carry an open question for the owner, a list of options for someone to pick from, or a value nobody chose (a fallback, a default, a limit), the request is intent-bound. That holds for a request labeled bug too: a bug whose fix needs a policy choice is intent-bound. Missing evidence or missing access never licenses inventing the policy; it is a needs-info question, routed as Route questions says.

A request can move from code-bound to intent-bound when research turns up an intent question. It moves back only when the owner's answers, or answers you infer under the inference test, settle every such question.

Triage a specific issue or PR

1. Gather context. Read the full issue or PR (body, comments, labels, author, dates; for a PR, the diff too). Parse prior triage notes and recorded owner decisions so you don't re-ask resolved questions. Read .out-of-scope/*.md and surface any that resembles this request (prior rejection). Read enough of the codebase, using the project's domain glossary and its ADRs, to sort the request. Pass any recorded owner-review reservation and its dated source to the brief's writer on either path.

Every research run, on either path, does two checks first:

• Redundancy: search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where it looked.
• Verify the claim. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims: check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail.

1. Recommend. Tell the maintainer your category, path (code-bound or intent-bound), and state recommendation with a one-line reason each. Continue unless they redirect you.

2. Take the request's path, below. Either path can end early: a redundant request is an already-implemented wontfix, a claim that fails verification or lacks detail is needs-info, and a rejected request is wontfix (see Other outcomes).

Code-bound path

1. Research. Start the research run with the issue link, its path, AGENT-BRIEF.md, the two checks, and this task: when the claim is confirmed, post the agent brief, followed by its triage notes, on the issue, and report any question it could not answer from code or logs instead of guessing at it.

2. Review. Read the published brief as a reviewer who did not write it. Check it against the issue and the code yourself, not against the research run's own summary:

   • Evidence: each claim the brief rests on traces to a code path, a reproduction, or the issue. Spot-check the one the change depends on. Verify every required input under Available inputs.
   • Scope: desired behavior is what the request asks for; nothing the request needs is dropped, nothing beyond it is added, and out of scope names the adjacent work an agent might reach for. Work that must be shown on a live system is split as AGENT-BRIEF.md says.
   • Acceptance criteria: each is concrete, testable, and independently verifiable, and together they cover the edge cases the request and the code expose.
   • Dependencies: work that must land first is named, so it can be recorded as a blocker.
   • Open questions: none remain, including missing required inputs. Route unavailable material as Route questions says. An open intent question, an option list, or an unchosen value means the request is intent-bound; switch paths.

   Passing the issue-contract check proves the shape, never that the brief holds. When it does not hold, send the research run the specific corrections; it edits the brief, and you review the new revision from the top.

3. Accept it, as below.

Intent-bound path

1. Fact-finding. Start the research run with the issue link, its path, the two checks, and this task: gather the code facts the owner's decision needs (current behavior, constraints, prior decisions in the issue, ADRs, and glossary, and the options with what each would cost), and write no brief yet. Post its findings as a triage notes comment when the owner will read them on the issue.

2. Infer what you can cite. Answer an intent question yourself only when all three hold:

   • Cited: you can cite the answer's source, with its date: the owner's approved goal for the work, a recorded owner decision, a recorded owner wish, or the owner's quoted words.
   • Reversible within the work: no value or policy outlives it, and it adds no public name and no breaking change. Never infer a default, limit, timeout, or fallback that persists in the product.
   • Within the goal: it changes neither the goal nor the scope.

   Otherwise the question goes to the owner. Each inferred answer is stated as behavior in the brief and listed with its citation under Inferred intent in the triage notes. List every inferred answer in your next report to the owner, so they can veto it; a veto is an owner decision, and the brief is revised from it. When you infer every intent question, have the research run write the brief from the facts and your inferred answers, then go to step 6.

3. Grill the owner on the questions you cannot infer, in a grilling session of its own. Open it with /grill-with-docs using the session's supported invocation, followed by task context: the issue links, the facts, your inferred answers, the recorded owner decisions, unresolved questions, scope and AGENT-BRIEF.md. Include the owned branch and checkout for domain-document edits, the per-repository pull request destinations and the workbench destination required by the contribution guide's Triage section. Its deliverables are the decision record and draft briefs in a proposed ticket split, with the report-back destination. Leave filing and readiness to yourself. When the owner cannot join a grill now, put the request in your decision inbox with your recommendation.

4. Decide the split. Merge, split, or drop a draft, or set it aside for later work. When your split changes a draft substantially, have the grill rewrite that brief; never write or rewrite one yourself. Start a research run to write a brief only when it needs code facts the grill did not gather.

5. File the issues with the grill's briefs: post each brief on its intake issue, or file a new issue for it. Each issue's triage notes record the owner decisions its brief relies on, pasted from the grill record, each with its date and where the owner gave it, so later triage reuses them.

6. Review each brief as on the code-bound path, as a reviewer who did not write it, and also refuse a brief that carries owner intent in disguise: a choice left to the implementing agent, an option list, a fallback or default nobody decided, or an open question. Route each such question as Route questions says, and accept only once every one the owner must answer is answered. A question a recorded decision already settles goes back to the brief's writer as a correction instead.

7. Accept each brief that holds, as below.

Accept a brief that holds

1. Wait for the revision notice the issue-contract workflow posts for the brief revision you reviewed. If the brief changed after your review, review the new revision. If no notice arrives, leave readiness to the owner and tell them the notice is missing.

2. Choose the readiness:

   • ready-for-human only when the work needs the owner's own accounts or credentials, or a taste call the owner reserved for themselves.
   • ready-for-agent with factory:skip for agent work the factory must not pick up, by the tests in the installed factory rules, which also say who creates the label and who merges. Without those rules there is no skip label.
   • ready-for-agent alone for any other work.

   When owner review before merge is reserved, in either profile, verify that the brief explicitly designates it as contract behavior and its triage notes retain the dated decision source. Check this even when that reason first arises here, after the initial brief review. If the designation or its source is missing or unclear, return the brief to its writer with the recorded reservation and source; the writer corrects it. Independently review the corrected brief from the top, then return to step 1 for its new validator revision notice before applying readiness. Never write or rewrite the brief you accept.

   Follow the github-repository-configuration rules' Designated owner review gate for delivery. Standard-profile delivery keeps its otherwise authorized merge actor; installed factory rules govern factory merge ownership and approval-pause continuation.

   For workflow-edit-only work without a separate owner-review designation, follow the ordinary applicable merge conditions in the installed rules; the skip marker alone supplies no designation.

3. Choose the model, when the installed rules ask for a model: label: weigh the triage notes' suggestion against the work, and pick one label yourself, including for the host default. Keep a matching model already on the issue, or remove a conflicting model before applying readiness; never infer a default.

4. Apply and confirm readiness with the bundled command, using the sha256: revision from the notice you reviewed and the companion labels you chose:

   node <this skill's directory>/ready.mjs <issue> ready-for-agent <sha256:reviewed-revision> <model-label>
   

   For ready-for-human, name the account, credential, or reserved taste call the work needs in a note, and omit the model label when none is needed. Additional companion labels, such as factory:skip, follow the revision; --repo owner/name selects another repository. Run with Node.js 24 or 26 in the foreground, bounded by the caller's command timeout. The command uses the current gh credential through the vendored Postern bundle and needs no install step. It checks account eligibility against the selected destination's installed factory workflow rules at its default-branch commit, independently of this checkout. Outside factory repositories, role-authorized person, bot and App reviewers use the same revision-bound flow; factory repositories require a person and refuse bot/App accounts before readiness writes. For factory non-parent agent readiness, it requires exactly one model in the combined existing and companion labels. It creates a missing chosen repository model label using the installed factory rules' color and description format, and preserves an existing label unchanged. Failed identity, applicability or model-label provisioning applies no readiness. Exit zero confirms the validator approved that revision by the acting account; a nonzero exit explains the refusal or rejection. Review a changed revision again before retrying. For a parent it waits for the latest child link and reapplies readiness when its timestamp is not newer than that link.

5. Record blockers. Add a native blocker for each issue whose work must land first.

6. Tell the owner what you accepted, with links to each brief, the labels you applied, the blockers you added, and every answer you inferred, so they can veto it.

When your credentials cannot apply readiness, stop at acceptance: tell the owner, with links, which revision holds, the readiness, model and skip labels you chose, and the blockers to record. When the command refuses your account because the destination's factory rules require a person, give those details to an authorized person in the same way and report that factory work has not started.

Other outcomes

• needs-info: route the missing information as Route questions says; for a question to an outside reporter, post triage notes (template below).
• For wontfix, close the issue, with the comment depending on why:
  • Already implemented: the change already exists in the codebase. Point to where it lives; do not write to .out-of-scope/ (that KB is for rejected requests, not built ones).
  • Rejected (bug): give a polite explanation, then close.
  • Rejected (enhancement): write to .out-of-scope/, link to it from a comment, then close (OUT-OF-SCOPE.md).
• needs-triage: apply the role. Optional comment if there's partial progress.

Route questions

Every question reaches you first, whoever raises it: a research run, a grill, or an agent's issue comment, including one under needs-info or factory:needs-input.

If an answer changes the implementation contract, send the edit to a separate writer; never write the revised brief you accept. Follow the contribution guide's validator-notice, independent-review and renewed-readiness steps before continuation; an unchanged contract needs no new readiness cycle.

• Answer what you can: from code, logs, or a reproduction, or by inference under the inference test.
• Ask an outside reporter what only they know, with the needs-info template below.
• Put an owner-only question in your decision inbox, with your recommendation. The decision inbox is the one channel for questions to the owner.
• An agent's question to the owner, posted as one issue comment under the contribution guide's owner-question rules: read it first. When the inference test lets you answer, answer on the issue, and remove factory:needs-input where the installed factory rules let the answerer remove it. Follow those rules for the order of marker removal and frontier release. Otherwise put it in your decision inbox.

Quick state override

If the maintainer says "move #42 to ready-for-agent", trust them: that is their review, not yours. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. Apply a readiness role through Apply and confirm readiness, with the revision from the issue's current revision notice and the model and skip labels the installed rules ask for; when the command refuses your account, hand the maintainer those details instead. If moving to ready-for-agent without a brief, ask whether they want one written.

Needs-info template

## Triage Notes

**What we've established so far:**

- point 1
- point 2

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

- question 1
- question 2

Capture everything resolved so far under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".

Resuming a previous session

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

Reads

Paths are relative to the repository root.

• CONTRIBUTING.md: its Triage, Readiness and Comments sections and its account policy. When it is missing, carry out this skill's method as written, starting each comment with the disclaimer above, and ask the owner for any rule the method leaves to the guide.
• The installed rules, such as the github-repository-configuration and factory workflow rules, which the repository-standards skill looks up. When they are missing, take the brief's shape from AGENT-BRIEF.md and the role meanings from this skill, and apply no model: or factory: label.
• AGENTS.md: its Agent skills requirements for delegation and session naming. When it is missing, give each research run only its task context, and name the session for its operation and target where naming is supported.
• docs/agents/issue-tracker.md: the issue-tracker config, including whether external pull requests are a request surface. When it is missing, triage issues only, and ask the user which tracker to use.
• docs/agents/triage-labels.md: the label string for each role. When it is missing, use the canonical role names as the label strings.
• .out-of-scope/, holding .out-of-scope/<concept>.md files: requests rejected before. When it is missing, none were; create it with the first rejection, as OUT-OF-SCOPE.md says.
• scripts/validate-issue-contract.mjs, Repo Canon's issue-contract validator, and the babysit skill's GitHub connection: ready.mjs imports both. When either is missing, ready.mjs cannot start: apply the readiness and companion labels with the tracker's own client, and confirm they hold on the issue.
• .repo-standards/rules/factory-workflow.md at the destination's default branch: ready.mjs reads it to tell whether factory rules apply. When it is missing there, the generic account policy applies.