---
name: triage
description: The bridge between a traditional issue tracker (GitHub Issues, Jira, Linear, …) and the AI-first SDLC. Two modes — **triage** (inbound — a tracker item is routed through the ownership index to its owning feature docs, localized with `nustack graph`, and lands as a confidence-graded triage dossier ready for a fix plan) and **file** (outbound — a verified harness finding becomes a tracker-native issue with checkable evidence, and the created ID is written back into the originating row). Tracker access goes through a connector (see the per-tracker packs under references/trackers/); tracker writes are always approval-gated per run. Use on "triage issue #N / PROJ-123 / ENG-123", "triage the new issues", "file this finding as a ticket", "/triage".
---

# triage — the tracker bridge method

> **No connector reachable** (no MCP server, no CLI, no API credentials — the pack for your tracker lists the probes): never stall. Accept pasted issue text, name the fields you are missing (labels, comments, linked items), and triage what you have, announced.

You bridge two systems of record. Neither is asked to change:

- **The tracker owns** intake, priority, assignment, status, discussion. You never relocate those.
- **The AI layer owns** intent (feature docs say *why* — invariants, vocabulary, scope), location (the ownership index and `nustack graph` say *what and where*), and history (git-derived).
- **The bridge rule: inbound enrich, outbound evidence.** An inbound item gains location, owning docs, and blast radius. An outbound item carries citations a human can verify without trusting you.

## Connectors

Tracker access is this skill's own knowledge, never a harness-declared tool: a tracker is reached through an MCP entry, one of several unrelated CLIs, or an env var, varying per repo and per team, so you probe for it at the moment of use. Each tracker's pack under [`references/trackers/`](references/trackers/) lists its access options in preference order — an MCP server, a CLI, the raw API, in the order that pack sets — with the probe for each, auth setup, and the exact calls for read / search / create / comment.

- **Always read the pack for your tracker before the first tracker call.**
- More than one tracker in play → one pack each; the method below is identical across all of them.

## Tool tier

Read the `nustack` status from the session context (`Tool:` line):

| Tier | Do |
| --- | --- |
| **Present-fresh** | Localize every question through `nustack graph` (`find`, `where-defined`, `who-calls`, `refs`, `impact`, `blame`, `tests-covering`) before reading source |
| **Present-stale** | Use it; note the gap |
| **Absent** | Glob/Grep/read, announced |

- **Never run an index step first** — the family re-indexes a stale store before it answers.
- **Syntax-level detail goes straight to source, whatever the tier** — decorator lists and their order, full function bodies, statement sequence are not in the index's query surface. Decorator *application* is indexed as a reference, attributed to the decorated declaration; what the decorator does is not.

## Mode selection

**Triage** when given issue references, a tracker query, or pasted issue text. **File** when given a harness finding to externalize — a backlog row, a drift or bookkeeping finding, an audit or critic result, a changelog discovery. Ambiguous → ask one question; never guess.

## Triage — tracker item in, dossier out

1. **Fetch** through the connector (per the pack). No access → pasted-text mode, missing fields named.
2. **Classify.** Bug / feature request / question / docs-gap. A question gets owning-doc pointers and a direct answer, not a dossier.
3. **Route.** Match the issue's vocabulary against the ownership index and feature docs' `keywords:`. Read the owning doc(s) **fully** — intent and invariants first, code second. No owning doc → say so; the absence is itself a finding.
4. **Localize.** Run names from the issue through `nustack graph` (per § Tool tier); every location claim carries `file:line`.
5. **Diagnose.** Write a root-cause hypothesis graded `certain` / `inferred` / `unresolved` — **never** present inferred as certain. Blast radius via `impact` / `coupling`; test surface via `tests-covering`.
6. **Dedup.** Search the tracker for siblings and priors (per the pack); check `nustack graph drift` for the same bug in a clone.
7. **Write the dossier** to `docs/operations/triage/YYYY-MM-DD-<tracker>-<id>-<slug>.md` and return the verdict summary.
8. **Post back** (comment, label, assign, transition) only under § Boundaries' approval gate: show exactly what would be posted, post only on an explicit yes in this session.

## The dossier

A dossier is a dated working artifact — it **never** claims `owns:` globs and never masquerades as a feature doc.

**Frontmatter:** `type: triage`, `tracker`, `date`, `confidence`, and the subject key:

| Subject | Key |
| --- | --- |
| A tracker item | `issue: {id: <n>, url: <url>}` — the id **numeric** |
| A locally-authored record | `issue: {id: local:<record-id>}` |
| A pull request the dossier resolves | `pr: {id: <n>}` |

**This key is machine-read:** the NuStack desktop's Issues panel joins dossiers to tracker rows on exactly this key, so a quoted number, a missing id, or a renamed key leaves the dossier orphaned — written but never surfaced beside its issue.

**Sections, in order:**

1. **Verdict** — 1–3 sentences.
2. Classification
3. Owning docs — paths.
4. Root cause — cited, graded.
5. Blast radius
6. Suggested fix plan — feeds the plan → PR loop; you never implement.
7. Test surface
8. Duplicates & related
9. **Prior-thread corrections** — claims already on the tracker thread (bot answers, maintainer comments) that your evidence shows to be wrong, each with the citation that refutes it.
10. Open questions

## File — harness finding in, tracker issue out

1. **Verify first.** Reproduce the finding against source before externalizing it. A claim that doesn't reproduce is reported back, never filed.
2. **Compose tracker-idiomatic** (per the pack): imperative title; body of one plain-language context paragraph (no harness jargon), evidence (`file:line`, commit hashes), expected vs actual, acceptance criteria; link the owning feature doc by path.
3. **Show the draft(s).** Create only on explicit approval, through the connector. Many findings → one draft list, one approval, then individual creation; report every created ID.
4. **Close the loop.** Write the created issue's ID/URL back into the originating row — a backlog row gains the link, a bookkeeping row resolves.

## Boundaries

- **Never edit source code.** The dossier ends at the fix *plan*; implementation belongs to the plan → verification → PR loop.
- **Nothing is created, edited, or commented in the tracker without explicit approval in the current run.** A standing repo ruling (e.g. "never post to this upstream") overrides any approval.
- **Repo writes are only** `docs/operations/triage/**` plus the loop-closing edits to `docs/history/backlog.md` / `docs/operations/bookkeeping.md`.
- **Announce every degraded mode** — degraded output is acceptable; silently downgraded evidence quality is not.