Merge remote-tracking branch 'gh/docs/wave-skill'

# Conflicts: # prolog-sessions/kb.pl
2026-09-20 19:39:51 -07:00
parent debad21556 5c3c796308
commit 3c5836c9d9
1 changed files with 83 additions and 0 deletions
@@ -0,0 +1,83 @@
+---
+name: wave
+description: Dispatch parallel agents to work through open beads and shepherd each to a merged PR. Use when an orchestrator is running a wave, partitioning the backlog, or writing a brief for a work-unit agent.
+---
+
+# Running a wave
+
+An orchestrator chunks the open backlog, fans agents out, reviews what comes
+back, and merges. `AGENTS.md` has the history; this is the operating procedure.
+
+## Every agent gets its own worktree. No exceptions.
+
+Dispatch with `isolation: "worktree"`. Without it every agent edits the **same**
+working tree: one `git status` shows four agents' half-finished files, any commit
+sweeps up the others' work, and any `git checkout` destroys it. This has happened
+here. If you discover it mid-wave, stop every agent, have each create a worktree
+and copy across **only files it can prove it touched**, then `git checkout --`
+those files in the primary tree.
+
+In the worktree: `direnv allow`, or `bd` reports a version *mismatch* rather than
+failing cleanly. `direnv status` prints `Found RC allowed 0`, and `0` means
+allowed — it reads like the opposite.
+
+## Partitioning
+
+By **crate or directory**, never by ticket count. **Tickets that share a file go
+to one agent**, to be done sequentially — four widget migrations all touching
+`src/draw.rs` are a guaranteed conflict split four ways. Group first, then count.
+
+Tell each agent what ground is *not* theirs, and to report rather than guess when
+it must cross. Two agents adding a workspace member will still collide in
+`Cargo.toml`/`Cargo.lock`; keep both sides.
+
+## What every brief must carry
+
+1. **The expected base commit, by name.** Worktrees do not reliably branch from
+   HEAD — one was created three merges behind and only noticed because it was
+   told to check.
+2. **The baseline**, so "N passing" is checkable rather than asserted: Rust test
+   count, harness counts, node counts.
+3. **Its ground, and the ground that is not.**
+4. **Never write** `.beads/**`, `prolog-sessions/kb.pl`, `context/repo-map.md`.
+   Agents read them freely and report proposed text; the orchestrator applies it.
+5. **The commit trailers and PR footer**, spelled out.
+6. **Do not push to `main`, do not merge.** The orchestrator merges.
+7. **What to report**: branch and head SHA, PR number, what changed per ticket,
+   *what could not be verified and why*, proposed repo-map/kb text, and **what it
+   learned that the ticket did not predict** — consistently the most valuable
+   part, and omitted unless asked for explicitly.
+
+## Method to require, because this repo's defect is a test that passes
+
+- Failing test first, then the fix.
+- Every guard proved by **injecting the fault it names** and watching it fail
+  **by name**. An injection that does not compile reads as a clean run, so
+  require a positive signal the build ran.
+- `cargo test --workspace` is **fail-fast**; `--no-fail-fast` for any claim about
+  blast radius.
+- A textually clean merge can **delete tests** with no conflict marker, and
+  `cargo check` will not notice. After any merge that moves a test module, diff
+  test **names** — a count is masked by the other side's additions.
+
+## Shepherding
+
+- Wait on checks with `scripts/pr-watch <pr> --expect <sha>`. Never hand-roll a
+  poll; see the `pr-watch` skill for the three ways they report green while wrong.
+- Review before merging. Copilot's quota may be exhausted and its request is a
+  **silent no-op**; an absent review and an unrequested one both read as
+  "pending". Dispatch an adversarial reviewer and give it the head SHA, the base,
+  and a test-merge, so it reviews the tree that will exist.
+- A re-review is of the **delta**, at a named SHA. A review of a superseded
+  commit reads as a pass.
+- Merge on GitHub, then `git fetch gh && git merge --ff-only gh/main`.
+- Anything posted to GitHub goes out under the owner's account: open every
+  comment with a line saying a Claude agent wrote it.
+
+## Between waves
+
+Run the code-review skill on the merged range. The characteristic find here is
+not a wrong line, it is **a test that passes while the thing it names is
+broken** — a vacuous fold test, a one-category fixture, a helper that fabricates
+what the code under test needs. Ask the reviewer to inject the fault and watch
+the check fail.