/triage-issue

name: triage-issue
user-invocable: true
version: 4.10.0
argument-hint: <issue-number> [more issue numbers…] | <audit-id> F<k> [F<j>…] | --prioritize-now <unit> F<k> [F<j>…]
author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Verify an issue, persisted audit finding, or unresolved review finding against
  current code, classify it, and write only the contracted forge/ledger
  outcome. Supports independent batches and a routed review-finding
  route: a `fix-now` row is handed to `/fold-findings`, never implemented
  here. Triggers: "triage-issue", "triage issue N", "triage this finding",
  "is this trigger met".

Triage Issue

Decide what happens to an issue, grounded in evidence — not vibes. Prevents both premature work (acting on a deferred item whose trigger is unmet) and silent rot (a fix-now bug left to drift).

Turn contract

Load and verify the **canonical** [Turn contract](../orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn. Skill-specific additions (the docs-language and `→ Next:` boxes are canonical-owned and not restated here):

✓ One fixed-format verdict block per issue (Trigger / Checked / Evidence / VERDICT / Action) — plus the summary table when batched
✓ Nothing deferred was implemented inline
✓ Audit-finding mode (`<audit-id> F<k>`): the audit file carries its `↳ triaged` note, and any opened issue cites `Origin: product audit <id>, finding F<k>`
✓ Review-finding mode (`--prioritize-now <unit> F<k>`): every named unresolved finding gets a verdict **and a route** — a `fix-now` row is routed to `/fold-findings` (or an explicit `/execute-phase <unit> P<n>`), never implemented in this turn
✓ Batched input? The closing recommendation maps every issue/finding ID to its own next command, joined with ` + `; it never collapses to one generic action

Missing reference → STOP. About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

When to use

• Any issue needing a decision: a freshly filed bug, a `postpone`/`needs-triage`

item, or a periodic re-confirmation of a deferred tradeoff.

• **Batch triage** — pass several numbers (`triage-issue 12 14 17`): each issue

gets its own independent verdict + evidence, then one summary table at the end. Batching applies to *triage only* — any resulting fix still gets its own branch and PR.

• **Audit findings** — `triage-issue <audit-id> F<k> [F<j> …]` triages findings

from a persisted `product-audit` report instead of existing issues (see *Audit-finding mode* below). Batching works the same way.

• **Review findings** — `triage-issue --prioritize-now <unit> F<k> [F<j> …]`

triages unresolved rows from the current feature/fix unit's findings carrier: its `## Findings` section in `SPEC.md` for a migrated unit (issue #308), or `review-findings.md` for a legacy one — probe the doc first, never both. This route is for findings that `fold-findings` could not close. `--prioritize-now` forces the fold route for the named rows in this turn instead of queuing them for a later turn; it does not permit a downgrade, postponement, or silent drop, and it never authorizes implementing them here — the fold owns the fix and the `folded:` flip.

Step 0 — Discover the project (always first)

**Backlog-sweep citation (S9 c, from #218).** Every newly opened issue must cite its backlog-sweep `Checked:` line in the body — procedural, auditable after the fact. When triaging a new issue on behalf of the user, the body includes a `Checked: <what was searched>` line.

Per the agent guide's **Workflow conventions** + **documentation map**, then read what THIS skill needs: the location index (e.g. `docs/ROADMAP.md`, whose `## Fixes` table is the fix index) and fix SPEC template, and the roadmap tables. **Retrieval aid (optional, never authoritative):** when the index entry point exists, run it once before the forge read — `agentic-workflow doc --query "<topic terms>" --json-only` — to surface prior findings, decisions and session-log entries on this topic. It is a fast path over the same corpus grep covers: a missing index, an absent entry point, or an empty answer changes nothing (grep stays the exhaustive fallback — AC21), and the index is never a decision authority. In review-finding mode, read the target unit's SPEC, acceptance, `review-findings.md`, current diff, and PR instead of looking for an issue comment. Otherwise read the issue in full, including comments and labels (forge CLI per the project's Workflow conventions — examples use `gh`):

gh issue view <N> --json number,title,body,labels,state,comments

Progressive loading — select the triage source

The reference allowlist is exactly the five linked paths below. Never invent or read another `references/` path. After Step 0:

• Forge issue number(s): read [issue process](references/ISSUE_PROCESS.md).
• Review finding(s): read [review finding process](references/REVIEW_FINDING_PROCESS.md).
• Persisted audit finding(s): first read

[audit findings](references/AUDIT_FINDINGS.md), then use the verification and decision steps in [issue process](references/ISSUE_PROCESS.md).

• Before applying an urgency or disposition label, read

[label vocabulary](references/LABELS.md); this file is the sole definition of names, colors, and mutation rules.

• Only when the verdict writes a row (`fix-in-unit` or `fix-now`), read

[fold ledger](references/FOLD_LEDGER.md) before writing the row.

Every resource is one hop from this file. A missing source artifact or required resource stops that item; batch items remain independent. Never invent a label, trigger, ledger row, verdict shape, or reference filename. A forge-issue `postpone` route loads exactly issue process then label vocabulary; it skips audit findings and fold ledger.

Guardrails

• The all-stage