From 8aaea6bfcc204605dd9a49824098f705e873c4d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Thu, 13 Aug 2026 00:45:59 +0000 Subject: [PATCH] the cost that matters is the useless wake, not the useful one Most waits find nothing almost always: a daily release check says no 360 days a year, and a branch watcher wakes on every push including everyone else. So the number to optimise is the useless wake times how many there will be. The fix is not a cheaper wake, it is pushing the relevance test into the wait condition so that firing implies relevance. Wait on a push THAT CONTAINS a COMMS file, not on a push. Wait on a version string that differs, not on a page that changed. Both are shell tests with no model in them. Three tiers, most events dying at the first: shell condition (free), fresh minimal agent (one small cold read), escalate with real context (a full read of a long session). A context-inheriting fork that returns nothing to the parent is tier two done well, but it is still a read, so it is the fallback for when relevance needs judgement rather than the default. For the platform this means a condition belongs in the declaration, not in the agent that wakes. Co-Authored-By: Claude Opus 5 --- docs/agent-waits.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) 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.