triage

name	triage
description	Move issues, external PRs, new ideas, manual test feedback, existing-codebase audits, and regression reports through workflow triage states. Use when Codex needs to classify work, verify claims, detect already-implemented behavior, ask for missing info, create agent-ready briefs, or route changes before implementation.

Triage

Move work through a small state machine so only clear, durable tasks reach implementation.

Read docs/agents/issue-tracker.md, docs/agents/triage-labels.md, docs/agents/domain.md, and docs/agents/verification.md if they exist. Resolve links, titles, branches, and "current work" yourself; do not require issue numbers.

Every comment or issue posted during triage must start with:

> *This was generated by AI during triage.*

Reference Docs

• AGENT-BRIEF.md — durable agent brief format.
• OUT-OF-SCOPE.md — rejected enhancement memory.

Roles

Category roles:

• bug — something is broken, including manual test failures and regressions.
• enhancement — new feature, product change, PRD, delivery slice, or improvement.
• audit — existing codebase capability check before deciding what to build.

State roles:

• needs-triage — maintainer needs to evaluate.
• needs-info — waiting on reporter or user.
• ready-for-agent — fully specified and safe for an agent to pick up.
• ready-for-human — needs human judgment, credentials, design authority, or manual action.
• wontfix — will not be actioned.

Each triaged item should carry one category and one state. Use the actual label strings from docs/agents/triage-labels.md.

Default Type to category mapping:

• bug -> bug
• audit -> audit
• PRD, slice, change -> enhancement

Common Entrypoints

New idea

Treat as an enhancement. Check whether an existing PRD, slice, issue, or code path already covers it. If it affects ongoing work, recommend replan steps rather than editing code.

Manual test feedback

Treat as a bug unless it is clearly expected behavior. Require reproduction steps, expected result, actual result, environment, artifacts/logs, and frequency. If these are missing, move to needs-info.

Existing-codebase audit

Treat as an audit. Do not implement. Produce an evidence matrix:

• Already satisfied, with evidence.
• Missing.
• Conflicting with existing behavior.
• Unknown, with the next fact needed.

Then recommend to-prd, to-issues, a single ready issue, needs-info, or wontfix.

Regression report

Treat as a bug with higher urgency. Record the broken previous capability, failing evidence, and the acceptance or CI blocker. Do not recommend merge while the regression is unresolved.

External PR

If docs/agents/issue-tracker.md says PRs are a request surface, triage external PRs like issues. For PRs, verify both the claim and the diff.

Process

1. Show What Needs Attention

When asked broadly, query the issue tracker and present:

1. Unlabeled items.
2. needs-triage items.
3. needs-info items with new reporter activity.
4. External PRs in scope.

Show counts and one-line summaries. Let the maintainer choose unless the user already specified a target.

2. Gather Context

Read the target issue, PR, local markdown item, feedback, or user-provided raw idea.

Explore the codebase enough to check:

• Redundancy: is this already implemented under project domain vocabulary?
• Prior rejection: does .out-of-scope/ contain a similar rejected enhancement?
• Relevant current behavior, interfaces, tests, CI, and docs.
• Related PRDs, slices, bug reports, or acceptance records.

For bugs and regressions, try to reproduce or identify the likely failing public interface before recommending implementation.

3. Recommend State

Tell the maintainer:

• Category and state recommendation.
• What evidence supports it.
• What remains unknown.
• Whether implementation should proceed, wait for info, go to PRD/slicing, or be rejected.

Wait for user direction before posting labels/comments unless the user explicitly asked you to apply the outcome.

If the user asks to "handle", "process", "capture", "create an issue for", or "整理为 bug/change/audit issue" and the facts are sufficient, create or update a durable work item and apply the category/state outcome. If facts are missing, create or update the work item as needs-info with specific questions rather than leaving the feedback only in chat.

4. Apply Outcome

ready-for-agent:

• Post an agent brief using AGENT-BRIEF.md.
• Include acceptance evidence and regression checks.

ready-for-human:

• Post the same structure, but explain why a human must act.

needs-info:

• Post concise triage notes with established facts and specific questions.

wontfix:

• For already implemented work, close with evidence and do not write .out-of-scope/.
• For rejected enhancements, update .out-of-scope/ and close.
• For invalid bugs, explain the verification result and close only when the maintainer confirms.

needs-triage:

• Apply the state and optionally record partial findings.

5. Resume Triage

If prior triage notes exist, read them first. Check whether the reporter answered outstanding questions. Do not re-ask resolved questions.

Needs-Info Template

## Triage Notes

**What we have established:**

- point 1

**What we still need:**

- specific question 1

Rules

• Do not edit product code during triage.
• Do not turn a vague request into implementation by guessing.
• Do not reopen a full PRD process for a single small issue if an agent-ready brief is enough.
• Do not close, merge, or mark done while a regression is unresolved.
• Preserve new ideas, manual feedback, and audit findings as durable tracker items, not chat-only context.