Triage

# Triage

Turn a batch of findings, requests, and issue-tracker items into grounded **change-request
bundles** — self-contained work packages the slice writer picks up later. Argument (optional):
path to a findings document (e.g., `tmp/uat_testing.md`).

The input can be a UAT run, a list of bugs, a change-request dump, chat discussion, or any
unstructured collection of issues. Triage understands it, groups it by subject, and writes one
bundle per group. **Triage does not write slices** — that is the slice writer's job, in a
separate, deliberate act.

## Triage is mandatory — and it stops at the bundle

- **Every change that will become a slice goes through triage first.** This is a hard rule. The
  bundle is the required input to `/write-slice`; there is no slicing without one.
- **Triage does not start `/write-slice` itself.** When the bundles are written, stop. The
  operator picks a bundle up later — usually in a fresh session — and runs `/write-slice` then.
  Do not assume the operator will action every bundle immediately.
- **The one exception is operator-initiated — never your own judgement.** Only when the **operator
  explicitly asks** you to carry straight on into `/write-slice` in the same session may you do so,
  and only if you also agree the request is a single isolated, genuinely minimal change (a clear bug
  fix, a cosmetic fix, an impactful-but-honestly-straightforward change). You never decide this on
  your own: absent an explicit operator request, you stop at the bundle, full stop. If the operator
  asks but you judge the change is not minimal, say so. Even when you do proceed, the bundle is still
  produced, the full slice-writing process still applies, and you **never** do this from a sub-agent.

## What this skill does

You are the orchestrator. You do not write application code, and you do not design the
implementation — you produce work packages that the slice writer (and, downstream, the dev
agents) execute.

## Procedure

### Phase 1: Collect and consolidate

**1a. Gather every input.** Read the findings document if one was passed. Pull in the relevant
chat discussion. Fetch the outstanding `Architecture`-tagged cards in the **Triage board's
Inbox** list — the project's intake queue. Leave cards tagged for other projects alone, and treat
untagged cards as not-yet-claimed; if asked to consider a card without the `Architecture` tag, say
so rather than adopting it. All three are inputs and are considered together.

**1b. Write a transient triage working document** at `../ArchitectureSpecs/handovers/triage_YYYY-MM-DD.md`
(transient docs live in `handovers/`, never at the specs root). Give every item a numbered entry
with:

- A clear description of the issue.
- Its source (findings-document reference, issue-tracker id, or both).

This document is scratch — it exists to drive the clarification loop and is **deleted at the end
of triage** (Phase 7), once all information has been absorbed into the bundles.

**1c. Clarify until you fully understand every item.** For every item that is vague, missing
information, or that simply needs research before it can be understood, add a **QUESTION** marker.
Present the document to the operator and iterate until every item is understood. Understanding the
request fully is the whole point of this phase — do not guess.

**Do not group items into bundles yet.** Phase 1 is about understanding individual items, not
deciding how they cluster.

### Phase 2: Ground enough to understand

Research items only to the depth needed to *understand* them — not to design or implement them.
The deep, file:line grounding that briefs depend on is the **slice writer's** job, not triage's.

- For an item whose meaning or feasibility is unclear, read the relevant code (use `Explore`
  sub-agents in parallel for groups of related items) until you understand what is actually being
  asked and whether it is coherent.
- Record findings back into the triage working document, and raise follow-up **QUESTION** markers
  where the code contradicts the reported behaviour or the request is ambiguous.
- If an item genuinely required research to understand, capture that research as a separate
  document — it becomes an attachment in the item's bundle (Phase 5).

A concrete goal of this phase is to gather enough information that you can group the items **with
confidence** in Phase 4 — you have to understand what each item really is before you can judge what
it belongs with. If you cannot yet tell where an item clusters, you do not understand it well enough.

Iterate follow-up questions with the operator until resolved or explicitly deferred.

### Phase 3: Separate non-actionable items

Identify items that should not become slice work:

- **Already implemented, or a duplicate** → **archive the card** (leave a short comment saying why).
  It never reaches a bundle.
- **Pure discussion / no actionable work** → flag for the operator.
- **Infrastructure or tooling work that bypasses the dev-agent slice workflow** (e.g. orchestrator
  tooling, infrastructure-only operations) → note it for the operator; it is handled outside slices.

Present the separation to the operator for confirmation before grouping.

### Phase 4: Group into logical categories

Group the remaining items into **change requests**. Follow these rules:

- **Group by related subject**, not by slice boundaries. You are deciding what work is *about the
  same thing*, not authoring slices. The slice writer decides slice boundaries later.
- **Do not use the number of API surfaces or applications touched as a grouping metric.**
  Delivering a feature end-to-end and correct matters more than limiting development complexity.
- **Favor larger groups.** It is easier for the slice writer to split one bundle into two slices
  than to notice adjacent work that was scattered across separate bundles and never came into
  view. When in doubt, group together.
- **Sanity-check against under-grouping.** Before finalizing, gla