wave-triage

name	wave-triage
description	Given the parcels belonging to a wave, compute merge order and gate status by combining parcel-roster inventory, parcel-reader claims, and parcel-audit verdicts against the wave's plan document. Surfaces: ready-to-merge, blocked, at-risk, and the next recommended merge. Triggers on: wave triage, wave status, what merges next, gate status, which parcels are blocked, wave readiness, merge order, wave plan.
allowed-tools	Read, Bash, Glob, Grep

Wave Triage

The end-to-end wave-level decision skill. Aggregates per-parcel signals into a single sequenced report that says: these parcels are ready to merge now, these are blocked and why, these are at-risk, and the next safe merge is X.

Bundled with rookery. Pairs with rookery status (live fleet view), rookery land history (what has actually landed on main), and rookery worktree list (raw worktree listing). This skill is the decision-grade narrative layer above those CLIs.

Treats the wave's plan document as the source of truth for dep-order and gate definitions.

When to use

• After a wave of parallel parcels has settled (most have written PARCEL_DONE.md)
• Before a merge pass, to confirm ordering is safe
• When a gate (per the wave plan) looks blocked and the user needs to know why
• Mid-wave to decide whether to spawn follow-up parcels (G-parcels) to unblock

When NOT to use

• You want a single-parcel verdict — use parcel-audit
• You want to know what worktrees exist at all — use parcel-roster
• You want to change merge policy — this skill reports; the lane owner decides

Path resolution (read this once per session)

This skill reads audits and worktree state under a configurable root. Resolve <worktrees_root> once, in this order:

1. rookery.yaml in CWD: read the worktrees_root key (top-level). Use this if present and non-empty.
2. ROOKERY_WORKTREES env var: fall back to this if step 1 yielded nothing.
3. Default: ./worktrees (relative to CWD).

Resolve the project repo root with git rev-parse --show-toplevel (run from CWD) — used for git -C <repo> log --grep=... lookups against main.

Audits live at <worktrees_root>/audits/.

Workflow

Step 1 — Identify the wave and its plan

Accept a wave id (e.g. wave-3) or a parcel-id list. If a wave id is given, Glob from <repo> for its plan:

docs/WAVE<N>_PLAN.md
docs/wave-<N>-plan.md
docs/waves/<N>.md

Read the plan in full. Extract:

• Parcel table: the canonical list of parcels in the wave with their scope (typically in a §2 or §Plan table)
• Dep graph: each parcel's "depends on" column
• Gates: gate definitions with their criteria (typically §Go/No-Go or §Gates)
• Parallelism plan: the ASCII timeline or dep diagram showing which parcels can run concurrently

If no plan file exists, proceed with just the parcel-id list — but note PLAN: absent in the report; merge-order recommendations will be advisory only.

Step 2 — Invoke parcel-roster

Use parcel-roster to get the fleet snapshot. Filter to the parcels in this wave (skip others). Note any parcels from the plan whose worktree is missing — they never started.

Step 3 — Per-parcel deep signal

For each parcel in the wave, gather three signals:

1. Completion claim — invoke parcel-reader on its PARCEL_DONE.md. Record whether present, what the summary says, any open-questions or stubs flagged.
2. Audit verdict — Glob <worktrees_root>/audits/<id>.v*.md, pick the highest version, Read it, extract the verdict line. If no audit exists, record AUDIT: absent.
3. Git state — ahead/behind/dirty counts from step 2's roster output.

Do not re-run the dev loop — that is parcel-audit's remit and is expensive. Trust the audit verdict, flag missing audits.

Step 4 — Compute gate status

For each gate in the plan, evaluate its criteria against step 3's signals. A gate is:

• open: all criteria met — downstream parcels may proceed
• blocked: one or more criteria unmet — list which and why
• partial: some criteria met, others in flight — useful during mid-wave triage

Do not relax criteria to make a gate pass. The plan's criteria are authoritative.

Step 5 — Compute merge order

Using the dep graph from step 1 and verdicts from step 3:

• A parcel is ready-to-merge if: audit verdict is PASS or PASS_WITH_WARNINGS, all deps are already merged (check git -C <repo> log --oneline --grep="<dep-id>"), no scope violations flagged
• A parcel is blocked if: audit verdict is FAIL, or a dep is not merged, or its PARCEL_DONE is absent
• A parcel is at-risk if: dirty worktree, or PARCEL_DONE present but audit missing, or audit is stale relative to commits (audit older than last commit)

Emit the next recommended merge as the ready-to-merge parcel with the fewest downstream dependents waiting on it (critical-path first).

Step 6 — Emit the structured report

WAVE: <wave-id>
PLAN: <path or "absent">
EVALUATED-AT: <ISO timestamp>

## Gate status

| Gate | Status | Blocked-by |
|---|---|---|
| G1 | open | — |
| G2 | blocked | I2 PARCEL_DONE absent |
| G3 | partial | I3 audit in progress |

## Ready to merge (in order)

1. <id> — <verdict> — <one-line rationale>
2. <id> — <verdict> — <one-line rationale>

## Blocked

| id | verdict | blocker |
|---|---|---|
| ... | FAIL | 3 mypy errors in ... |

## At-risk

| id | issue | remediation |
|---|---|---|
| ... | audit stale (3 commits since v1) | re-run parcel-audit |

## Missing from the plan

| id (expected) | status |
|---|---|
| ... | worktree absent — never started |

## Next recommended action

<one sentence: e.g. "Merge parcel X; it unblocks the longest downstream chain.">

Step 7 — Do not act

The skill reports. Merging, re-auditing, and authoring follow-up parcels are other concerns. The report is the product; hand-off is implicit. Operators can cross-check against rookery land history to see what has already landed.

Hard rules

Rule	Why
Plan document is authoritative for dep-order and gate criteria	Single source of truth; prevents drift between sessions
Never relax a gate criterion to make it pass	Gates exist to catch what parcels miss
Trust parcel-audit verdicts; do not re-verify	Audits are already expensive; triage is cheap by design
Report only; never merge, re-audit, or re-author	Triage is a decision-aid, not an action
Use parcel-roster + parcel-reader — do not duplicate their logic	Single source of truth for inventory and parsing
Resolve <worktrees_root> from config, never hardcode	Different deployments use different roots

Anti-patterns

Anti-pattern	Why it hurts
Inferring a gate's criteria from the parcel list when the plan is present	The plan is the spec; inference is hallucination
Declaring a parcel ready-to-merge with an absent audit	Audit is the sign-off — absence is a hard block, not a warning
Sorting the ready-to-merge list by parcel id instead of by downstream-impact	Critical-path first minimises wall-clock; id sort is arbitrary
Collapsing blocked and at-risk into one bucket	They need different follow-ups; merging them loses signal
Invoking parcel-audit from this skill	Audits are expensive; if one is missing the answer is "ask the auditor" not "do it here"

See also

• parcel-roster — fleet-wide inventory; step 2 input
• parcel-reader — PARCEL_DONE parsing; step 3 input
• parcel-audit — verdict source; step 3 input
• parcel-generate — authors the specs whose gates this skill evaluates against
• rookery status / rookery land history / rookery worktree list — CLI counterparts

Note on multi-role context

Wave triage assumes a wave is a coordinated batch of parcels with a written plan and gates. In a single-role / single-session workflow this collapses to "audit each parcel and decide which lands first" — most of step 4 (gate status) becomes degenerate. Skip the gate table in that case and emit only the Ready to merge / Blocked / At-risk sections; the rest of the workflow still applies.