diff --git a/docs/agent-waits.md b/docs/agent-waits.md index bb29f3d9..14929d2b 100644 --- a/docs/agent-waits.md +++ b/docs/agent-waits.md @@ -99,6 +99,39 @@ is the intuitive design and its expense is invisible, which is why it needs sayi --- +## Make firing mean something + +The rest of this file is about how to wait cheaply. This section is about the other half, and it is the one +that decides whether a fleet of these is affordable. + +**Most waits find nothing, almost always.** A daily release check answers "no" 360 days a year. A branch +watcher wakes on every push, including everyone else's. So the number that matters is not the cost of a +useful wake — it is the cost of a useless one, multiplied by how many there will be. + +The fix is not a cheaper wake. It is to **push the relevance test into the wait condition**, so that firing +already implies relevance: + +- **Do not** wait on "a push", then wake and check whether it carries a `COMMS//NN-*.md`. Wait on a + push *that contains one* — a filename test the shell can do with no model at all. +- **Do not** wait on "the releases page changed", then wake and read it. Wait on "the version string differs + from my cursor" — a string compare. + +Three tiers, and almost everything should die at the first: + +| tier | cost | for | +|---|---|---| +| **shell condition** | zero | anything expressible as a filename, a diff, a version, a status | +| **fresh minimal agent** | one small cold read | relevance genuinely needs judgement, but not history | +| **escalate with real context** | a full read of a long session | the event has to be interpreted against what came before | + +A session fork that inherits context but returns nothing to it (Claude Code's `/btw`) is tier two done well. +It is still a context read, so it is the fallback when a shell test cannot express relevance — not the +default. + +**Corollary for the platform:** a wait's condition should be part of its declaration, not something the agent +evaluates after waking. `wait for: push to touching COMMS/**` is a cheaper and more honest thing to +build than `wait for: push` plus an agent that decides. + ## The contract a wait must honour Specification. None of this is built yet.