triage-issue
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 an immediate-fix review-finding route. Triggers: "triage-issue", "triage issue N", "triag
Install
npx skills add https://github.com/gtrabanco/agentic-workflow/tree/main/skills/triage-issue
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gtrabanco-agentic-workflow@llmmart
git clone https://github.com/gtrabanco/agentic-workflow.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gtrabanco/agentic-workflow collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 — verify before ending the turn
✓ 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
✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
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-triageitem, 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 persistedproduct-auditreport 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## Findingssection inSPEC.mdfor a migrated unit (issue #308), orreview-findings.mdfor a legacy one — probe the doc first, never both. This route is for findings thatfold-findingscould not close.--prioritize-nowforces 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 thefolded: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.
- Review finding(s): read review finding process.
- Persisted audit finding(s): first read audit findings, then use the verification and decision steps in issue process.
- Before applying an urgency or disposition label, read label vocabulary; this file is the sole definition of names, colors, and mutation rules.
- Only when the verdict writes a row (
fix-in-unitorfix-now), read fold ledger 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-stages no-assumption rule binds verification work — ask-don't-infer,
owner
skills/unit-lane/references/DESIGN.md(ask-dont-infer@1): a trigger the tree does not evidence is checked and asked about, never assumed. - Don't build deferred work just because asked to "look at" the issue — surface that the trigger is unmet and stop.
- Keep issues, the fix index, and docs in sync with reality.
- Otherwise per the project's Workflow conventions (docs-language, evidence): state exactly what you checked.
Portability
Use the project's declared forge CLI and translate commands one-for-one. The classification, label ownership, and persisted-output contracts do not change.
Relationship to other skills
┌─ fix-now ─────────▶ /unit-lane --fix <n> ─▶ the lane's implement step
├─ fix-in-unit ─────▶ execute-phase <NN> P<k> (fold into phase)
triage-issue ────┤ or fold-findings (ledger row)
│ or unit-route <unit> → /unit-lane <unit> (replan)
├─ promote ─────────▶ /unit-lane --from-issue <n> (feature from issue)
├─ postpone ────────▶ dated comment, leave open
└─ wontfix ─────────▶ propose close
In review-finding mode, replan-in-unit runs bun scripts/unit-route.mjs <unit> (node fallback if bun is not installed): its route: replan line prints
the planner command — /unit-lane <unit> for a feature, /unit-lane --fix <n>
for a fix — which re-runs the
lane's plan catalog step and appends new P<n> phases to the same unit. The
lane's own review step is the gate before execution. The user manually runs
those phases; this skill never implements them.
Done when
The issue has a clear verdict with cited evidence.
Each review finding has a clear verdict with cited evidence; an oversized finding has an explicit planning command and a manual
/execute-phasehand-off.The verdict is recorded (routed, commented, and/or index-updated), and nothing deferred was implemented inline.
The closing
→ Next:block is printed per verdict:Single issue: → Next: <command for the recorded verdict> — act on the issue's evidence-backed action Batch: → Next: apply every verdict: #<n1> → <command> + #<n2> → <command> + #<n3> → <command> · fix-now → /unit-lane --fix <n> · promote → /unit-lane --from-issue <n> · fix-in-unit → /execute-phase <NN> P<k> or /fold-findings — never a new planner skill · postpone → dated comment, leave open · wontfix → propose close · same inconsistency across several issues → /product-audit (a recurring pattern, not isolated tickets — sweep the product rather than triaging one by one)Replace every placeholder with every actual issue/finding ID and its recorded route before printing; never print
<n2>,<command>, or…in a live batch.The
/product-auditline fires only on a recurring inconsistency — the same underlying problem behind multiple issues, not any single triage.
Files (agentic-workflow)
-
references
-
AUDIT_FINDINGS.md 2.1 KB
Loading… -
FOLD_LEDGER.md 2.3 KB
Loading… -
ISSUE_PROCESS.md 6.4 KB
Loading… -
LABELS.md 5.7 KB
Loading… -
REVIEW_FINDING_PROCESS.md 3.5 KB
Loading…
-
-
SKILL.md 9.2 KB
--- 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 — verify before ending the turn ``` ✓ 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 ✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise ✓ The closing `→ Next:` block is printed as the ABSOLUTE last output ``` 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`): ```sh 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-stages no-assumption rule binds verification work — **ask-don't-infer**, owner `skills/unit-lane/references/DESIGN.md` (`ask-dont-infer@1`): a trigger the tree does not evidence is checked and asked about, never assumed. - Don't build deferred work just because asked to "look at" the issue — surface that the trigger is unmet and stop. - Keep issues, the fix index, and docs in sync with reality. - Otherwise per the project's **Workflow conventions** (docs-language, evidence): state exactly what you checked. ## Portability Use the project's declared forge CLI and translate commands one-for-one. The classification, label ownership, and persisted-output contracts do not change. ## Relationship to other skills ``` ┌─ fix-now ─────────▶ /unit-lane --fix <n> ─▶ the lane's implement step ├─ fix-in-unit ─────▶ execute-phase <NN> P<k> (fold into phase) triage-issue ────┤ or fold-findings (ledger row) │ or unit-route <unit> → /unit-lane <unit> (replan) ├─ promote ─────────▶ /unit-lane --from-issue <n> (feature from issue) ├─ postpone ────────▶ dated comment, leave open └─ wontfix ─────────▶ propose close ``` In review-finding mode, `replan-in-unit` runs `bun scripts/unit-route.mjs <unit>` (node fallback if bun is not installed): its `route: replan` line prints the planner command — `/unit-lane <unit>` for a feature, `/unit-lane --fix <n>` for a fix — which re-runs the lane's `plan` catalog step and appends new `P<n>` phases to the same unit. The lane's own `review` step is the gate before execution. The user manually runs those phases; this skill never implements them. ## Done when - The issue has a clear verdict with cited evidence. - Each review finding has a clear verdict with cited evidence; an oversized finding has an explicit planning command and a manual `/execute-phase` hand-off. - The verdict is recorded (routed, commented, and/or index-updated), and nothing deferred was implemented inline. - **The closing `→ Next:` block is printed** per verdict: ``` Single issue: → Next: <command for the recorded verdict> — act on the issue's evidence-backed action Batch: → Next: apply every verdict: #<n1> → <command> + #<n2> → <command> + #<n3> → <command> · fix-now → /unit-lane --fix <n> · promote → /unit-lane --from-issue <n> · fix-in-unit → /execute-phase <NN> P<k> or /fold-findings — never a new planner skill · postpone → dated comment, leave open · wontfix → propose close · same inconsistency across several issues → /product-audit (a recurring pattern, not isolated tickets — sweep the product rather than triaging one by one) ``` Replace every placeholder with every actual issue/finding ID and its recorded route before printing; never print `<n2>`, `<command>`, or `…` in a live batch. The `/product-audit` line fires **only on a recurring inconsistency** — the same underlying problem behind multiple issues, not any single triage.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.