Triage

<!-- Copyright 2026 Anthropic PBC -->

<!-- SPDX-License-Identifier: Apache-2.0 -->

Triage

Standing rules in CLAUDE.md apply — especially: propose, don't act (rule 1); every claim carries a link (rule 4); data before theory (rule 5); log to lessons.md without asking (rule 8).

Procedure

1. Load context. Read ONCALL.md (policy + routing), STACK.md (capability bindings), and lessons.md (known causes) from disk. Files over memory (rule 7).

2. Classify the symptom. Match against the failure classes in references/:

   Symptom looks like	Load
   Tests failing, flaking, or silently not running	references/test-failures.md
   PRs stuck, queue depth growing, merges slow	references/merge-queue.md
   Jobs not starting, agents stuck, capacity errors	references/runner-infra.md
   Bad deploy, rollout stuck, post-deploy regression	references/deploy-rollout.md
   None of the above	No reference — say so explicitly, and investigate from first principles: timeline first (what changed around onset — deploys, flags, config), then blast radius, then narrow.

   (Classes are the CI defaults; your setup phase may have replaced them. The table above must match the files actually present in references/ — if they've diverged, trust the directory and flag the drift.)

3. Check the log first. Search lessons.md for this class's #tag and read the matching entries — never ingest the whole file; it grows unbounded by design. A matching past incident is your first hypothesis — cheapest to confirm or kill.

3a. Correlate before you classify. Sweep the other alert channels (and the incidents binding) for the same time window. Five alerts are often one incident: if this symptom is downstream of something already broken — a cluster problem, a shared dependency, another team's incident — say so in the diagnosis ("correlates with X in #infra-alerts; likely one incident, not five") and route to the upstream owner instead of investigating the echo.

3b. Alert storms get ONE triage, not one each. If several alerts have landed in a short window — or new alerts arrive while you're already investigating — treat them as a batch: group by likely common cause, run a single investigation for the group, and post one diagnosis that lists every alert it accounts for ("these 14 alerts trace to one upstream: …"). If an incident record is already open for the cause, attach new alerts to it (post in its thread/record) instead of opening a parallel investigation. If the batch looks like a real incident and no record exists, propose declaring one per ONCALL.md — a human declares it (the incident-record invariant); you never do. Batching is for shared cause only: if the evidence says the batch contains genuinely unrelated failures, say so explicitly and treat them as distinct incidents — separate diagnoses, separate records, each with its own severity call. Never merge for tidiness.

4. Run the reference's first checks against the bound capabilities in STACK.md. Establish the timeline: when did the symptom start, and what changed within the preceding window — deploys, flags change history, config, merges?

4a. Fan-out (page-severity only; sequential is the default below it). Where the channel's platform supports spawning parallel subagents, you are the orchestrator: spawn one investigator per bound source of truth the reference's first checks touch — metrics, logs, code/deploys, pager, alert-channels. Each investigator receives exactly four things: the symptom sentence, the onset window, its binding line from STACK.md, and the reference's first-check queries for its source — nothing else, so a poisoned thread can't steer it (rule 9a applies inside subagents too). Each returns the fixed shape:

• CHECKED: queries run, with links
• FOUND: observations with timestamps — observations, never root causes
• NOT FOUND: what was looked for and absent — absence counts only if the run/window was complete
• CANNOT ACCESS: anything that 403'd or timed out (surfaces in the diagnosis as a gap, never silently dropped)

Synthesis is yours alone: correlate, deconflict (two investigators dating onset differently is itself a finding), and write the one diagnosis. Fan-out multiplies token cost — worth it for a page, never for a morning-log item.

5. Apply the reference's correlation table. Where observations match a row, you have a candidate root cause; verify it against the timeline before promoting it (rule 5).

5a. Cross-check blame against "still happening" (CLAUDE.md rule 5a). A blame verdict — bisect, revert notice, "that PR broke it" — names the change that started the failure; before naming it as the live cause, confirm the symptom appears in the most recent completed run/window. Presence always confirms red; absence confirms green only on a completed run.