triage

name	triage
description	Move issues through evidence-backed category and readiness states.

Triage

Move issues through a small, explicit state machine. Read docs/agents/issue-tracker.md, the domain glossary, relevant ADRs, and the active initiative RUN.md before changing tracker state.

Every public tracker comment generated during triage starts with:

> *This was generated by AI during triage.*

References

• AGENT-BRIEF.md — durable agent-ready brief
• OUT-OF-SCOPE.md — rejected-request knowledge base

Labels

Categories:

• bug — accepted behavior is broken
• enhancement — new behavior or an improvement

States:

• needs-triage — evaluation has not finished
• needs-info — a precise missing input blocks evaluation
• ready-for-agent — acceptance, evidence, authority, and boundaries are sufficient for autonomous work
• ready-for-human — judgment or authority outside the active controller envelope is required
• wontfix — the request is rejected or already implemented

Each actionable issue has exactly one category and one state. A fully specified child that is dependency-blocked is the one exception: it keeps its category and explicit Blocked by edges but no state label until it enters the frontier. agents/scripts/setup-labels.sh creates the vocabulary idempotently.

Authority modes

Interactive is the default. Recommend an outcome, wait for the maintainer, then apply it.

Controller mode exists only when an active initiative RUN.md explicitly delegates tracker decisions to a top-level controller. Inside that envelope, controller sign-off satisfies routine approval and triage may mutate labels, post briefs, split/reorder in-scope work, and advance without asking the operator. It must stop at the RUN.md boundary.

Recommendation-only gathers evidence and reports a proposed outcome without mutating the tracker. Use it for untrusted or read-only callers.

Authentication, sessions, authorization, deletion, data integrity, secrets, and production deployment require explicit acceptance criteria plus independent security/operations review. Outside a delegated goal they are ready-for-human; inside a goal that explicitly includes them, the controller owns routine approval but may not weaken review or change the governing invariant.

Discover work

Show, oldest first:

1. unlabeled issues;
2. needs-triage issues;
3. needs-info issues with new reporter evidence.

External requests begin as issues. Pull requests carry already-accepted work through review and are inspected only when named or when the tracker configuration explicitly admits them to triage.

Triage one item

1. Gather. Read the full issue, comments, labels, author, dates, and any attached PR diff. Read prior triage notes. Search the codebase by domain concept for existing behavior and prior rejected requests.
2. Recommend. State the category/state, relevant code paths, redundancy result, prior decisions, confidence, and any missing authority. In interactive mode, wait; in controller mode, approve or reject within the envelope; in recommendation-only mode, continue only through safe verification.
3. Verify. Reproduce a bug with synthetic fixtures or prove the requested behavior/diff against executable seams. Report confirmed, contradicted, or insufficient detail with commands and results. Never use private or production-derived content.
4. Shape. When behavior remains ambiguous, use grilling and domain modeling. Persist settled terminology/ADRs and update the brief; controller mode may resolve only reversible choices already inside the PRD.
5. Apply. Post the durable brief for ready-for-agent or ready-for-human; post precise questions for needs-info; close a rejected request with rationale and record durable product rejection when appropriate; or leave needs-triage with evidence gathered so far.

Recommendation-only stops after step 3 with one consolidated report.

Safety

• Never expose credentials, Invitation values, private Bundle content, Viewer PII, or private provider evidence in issues or comments.
• Never contact real Viewers, send messages, or mutate production merely to reproduce a report.
• Prefer deterministic tests, synthetic fixtures, and local/provider-fake harnesses.
• A trust-contract, license, ownership, public-access, paid-service, or destructive external-state change cannot become ready-for-agent without explicit operator authority.

Agent brief

A ready-for-agent brief follows AGENT-BRIEF.md and includes:

• problem and observable acceptance;
• canonical PRD/ADR references;
• allowed and forbidden edit surfaces;
• behavioral test seam and exact verification;
• blockers/dependencies and baseline commit;
• security, privacy, documentation, and harvest requirements.

For a bug, the implementation path is diagnosis → failing regression → minimal repair → targeted/full checks → independent Standards and Spec review → repair/rereview → integration.

Needs-info template

> *This was generated by AI during triage.*

## Triage Notes

**Established**

- evidence already known

**Needed**

- one precise, answerable question

Do not re-ask a question answered in the issue history.