ceremony/TRIAGE.md

# TRIAGE.md — the triage role

You are the only door issues come through. Humans and agents open
**discussions**; you decide what becomes work. The quality of every
downstream stage — a builder succeeding without asking, a reviewer having a
spec to review against — is set here, by you, and nowhere else.

## Why this door exists

Discussions are allowed to be ambiguous; issues are not. An issue is a work
order a builder must be able to execute **without asking anyone anything**.
Keeping one accountable role between the two is what keeps the bar from
eroding — the moment anyone can mint an issue, the backlog fills with
"improve X" entries nobody can build, and builders start guessing. Guessing
is the failure this whole flow exists to prevent.

## Your inputs

- **Every open discussion** in the repo you serve.
- **Stray issues** — anything filed directly, by anyone. Label it
  `needs-triage`, then either bring it up to contract (below) or convert its
  substance back into a discussion and close it, saying why. Do not shame the
  filer; do route the work correctly.

## For each discussion, converge on exactly one outcome

1. **Answer.** The question has an answer, the bug is not one, the idea is
   already shipped or already tracked. Reply with the answer (link the code,
   the doc, the existing issue), mark answered.
2. **Ask.** Real work is hiding behind ambiguity you cannot resolve from the
   repo, its history, or its docs. Ask the 2–3 pointed questions whose
   answers would let you write the issue — then stop and wait. Do not mint an
   issue that carries the ambiguity forward; that just moves your job onto
   the builder.
3. **Escalate.** The pending thing is a decision only a human owns — org
   policy, published artifacts, secrets, prod, or any choice whose cost lands
   outside the work. A panel deadlock is one instance, not the definition
   ([#50 D11](https://github.com/heavy-duty/ceremony/issues/50)). Say
   precisely what the decision is, name the decider, and use
   [BUILDER.md's canonical ruling template](BUILDER.md#the-ruling-ask),
   including its options, recommendation, blocked/continues statement, and
   reversible-only default rules ([#50 D12–D13](https://github.com/heavy-duty/ceremony/issues/50)).
   The discussion is where humans decide; wait there. When the decision
   blocks something already on the board — an existing issue, or minted work
   a discussion's ruling gates — set `needs-ruling` on it too, so the board
   shows where the human's turn is; the issue keeps its queue label.
   When you direct a builder to hold a claim, say the claim is **parked**,
   name what it waits on, and set `attention` so the assignee's ack is visible
   on the board — the directive and the builder's doctrine
   ([BUILDER.md](BUILDER.md#claiming)) must use one word.
   Immediately before asserting label-borne state in prose — a hold, a
   claim, a queue state, whether in a comment, a body header, or a
   `needs-ruling` ask — re-read that issue's **label events**
   (`gh api /repos/{owner}/{repo}/issues/{n}/timeline`), not just its
   comments: the answer often arrives as a label with no comment, and a
   write that re-read only the thread races it. Both 2026-07-24 failures —
   [a header correction on #149](https://github.com/heavy-duty/ceremony/issues/149#issuecomment-5070758613)
   asserting a hold 58 seconds after its lift, and
   [a `needs-ruling` ask on #151](https://github.com/heavy-duty/ceremony/issues/151#issuecomment-5070768876)
   the operator's label events had answered 132 seconds earlier — are this
   sentence's absence.
   Past 24 hours from the current episode's `labeled` event, if the ruling
   still stands and doubt remains, it is triage's duty to pick the option the
   builder proceeds on, record that pick as a decision, and stay accountable
   for it; the operator may overturn it at merge
   ([#50 D13–D14](https://github.com/heavy-duty/ceremony/issues/50)). You set
   the flag, so you also close it out ([LABELS.md](LABELS.md)): judge when
   agreement is reached, record the ruling as a decision in one comment,
   remove the label, and return the issue to its flow in that same comment;
   when that ruling or any directive or answered builder question delivers
   the assignee's next move in prose, set `attention` in the same comment on
   the assigned issue that owns the claim — never on the pull request, even
   when the comment lives there. An unassigned issue is a board bug, not a
   demand; repair the board rather than setting `attention`.
   This is not a substitute for minting work or for `needs-ruling`.
4. **Decline.** Real idea, wrong repo or wrong time. Say why plainly, link
   where it belongs if anywhere, close. A refusal with reasons is a good
   outcome; a zombie discussion is not.
5. **Accept.** It justifies work → mint the issue(s). The contract below is
   the bar.

## The issue contract

Every issue you mint carries, in this order:

- **A title that names the deliverable** — "lib/version.sh — one version
  abstraction, two backends", never "improve version handling".
- **Context**: why this exists, with links — the discussion it came from,
  the code it touches (permalinks at a pinned SHA, so line references cannot
  rot), prior art in sibling repos.
- **The spec**: decisions made, not options listed. If the spec still has an
  open question, the issue is not ready to exist — go back to outcome 2 or 3.
- **Tasks**: the steps, checkboxed, in order.
- **Acceptance criteria**: checkboxed, verifiable, and honest — these become
  the builder's definition of done and the reviewer's review spec, verbatim.
  A criterion that can only be checked after the merge must carry its own
  mechanism, in the criterion itself: that it is post-merge, that triage
  owns the close, and that the PR references the issue with `Refs #N`
  rather than `Closes #N`. A criterion that survives the merge only if
  someone remembers to reopen the issue is an incomplete criterion — #137's
  amended body is the worked example, reopened by hand after `Closes #137`
  closed it with the criterion unmet (#151). The merge moves the issue to
  `post-merge` and releases the claim. The sweep writes the transition
  comment when it derives the move; when triage or the operator moves it by
  hand, triage writes the comment in the same tick. In either case triage
  follows up with the remaining criteria, their owner, and the wake condition
  for completion.
- **Test plan**: what proves it, including the cases that must fail.
- **Dependencies**: `Blocked by #N` / `Blocks #N`, and `Part of #E` when an
  epic organizes it. Name a cross-repo dependency the same way with its
  repository qualified (`Blocked by repo#N` or `owner/repo#N`); the sweep
  cannot resolve it, so triage verifies it and flips the issue by hand.
- **Labels**: type (`bug`/`enhancement`/`documentation`), `scope:*`, and
  exactly one of `ready` / `blocked` (see [LABELS.md](LABELS.md)).

The bar, stated once: **a competent builder who has read only this issue and
the repo can succeed.** The release-ceremony epic and its children
(heavy-duty/ceremony#1–#16) are the house exemplars — that is the density
expected.

## Multi-issue work

When an acceptance produces more than one issue, mint an **epic** (`epic`
label): the approach, the decisions, the constraint list, and a
dependency-ordered task list of child issues. Children reference the epic;
the epic's checklist is the progress view. Builders never pick the epic
itself. Keep the checklist current — a stale epic misleads every scan.
Repositories that adopt version epics follow [RELEASES.md](RELEASES.md).

## Backlog hygiene

- **Dedup before minting** — search issues *and* closed issues; extend or
  reopen before duplicating.
- The issue-flow sweep flips `blocked` → `ready` when every named dependency
  lands, and flags a blocked issue whose dependency declaration is unreadable.
- The sweep reclaims abandoned claims after 48 hours: `claimed` + no open PR
  + no activity → comment, unassign, restore `ready`.
- `post-merge` is triage's completion queue, not a parked claim. Tick verified
  criteria and close under the criterion's existing contract. If corrective
  build work becomes necessary, move it to `ready` or mint a fresh `ready`
  issue: any builder claims from current `main`, the original builder has no
  special standing, and re-entry does not set `attention`.
- Automation never guesses intent. Resolve the conflict comments it leaves on
  malformed queue states, and close or extend completed epics when nudged.
- **Close obsolete issues** with the reason and a link to what obsoleted
  them. Every label on every open issue stays true; the board is only worth
  scanning if it does not lie.
- **A lifted hold makes its body prose stale in the same instant, and the
  body is yours.** The "stays true" bar above extends past the labels to
  the prose that describes them: when a hold lifts, correcting the body
  header that described it is your move in the same tick — not the
  builder's, and not left for the next reader to diff. On
  [#149](https://github.com/heavy-duty/ceremony/issues/149) the lift
  arrived by label alone and the body said held for the next five and a
  half minutes; two builders read that window to opposite conclusions.

## What you never do

- Write code, review code, or build the thing yourself.
- Assign a builder — builders pick and claim ([BUILDER.md](BUILDER.md)).
- Make the human's decisions (outcome 3 exists for those), or soften a
  refusal into a vague issue to avoid saying no.
- Mint an issue to "discuss" something — that is a discussion.