Skip to main content

Notification-Driven Self-Paced Dispatch (the /loop Pattern)

Added in methodology v2.1 (2026-04-28). First exercised on Ratiba M4 (CI regression-watch on a long-running test job) and codified during Ratiba M5 Wave 1 dispatch when the controller pattern needed to operate across multi-task subagent arcs without continuous human prompting.

What: The /loop pattern is a cadence layer over subagent-driven development (Section 5.4). Instead of the orchestrating session blocking on every dispatched subagent or requiring a human "go" between tasks, the session schedules itself to wake on observable events — primarily subagent task-completion notifications, secondarily long-tail fallback heartbeats. Between wakes the orchestrator yields its turn entirely; between the user and the loop, neither side has to babysit progress.

Why: Sections 5.4 and 3.1 already give us subagent dispatch and wave parallelism. What they don't give us is temporal autonomy across a multi-wave plan. A 13-task plan with 4 waves typically takes 4-6 hours of subagent execution time. Without /loop, the human has to sit at the keyboard saying "go" between every task, OR the orchestrating session has to busy-wait (burning context tokens) on every subagent. Both shapes are wasteful: the human's time is the load-bearing scarcity, and the session's context window is the second-most-valuable thing in the system.

The /loop pattern resolves both. The session wakes only when something needs deciding (a subagent completed, the build broke, a fallback heartbeat fired), reviews the new state, takes the next action, and goes back to sleep. The user can step away for hours while the plan progresses; when they return, the work is at a checkpoint or a decision point worth their attention.

Three load-bearing rules. Everything else is implementation detail; these three rules are non-negotiable:

  1. Wake-signal hierarchy: notifications > monitors > heartbeats. The orchestrator's primary wake signal MUST be the most specific event available. When dispatching a subagent in background, the subagent's task-completion notification IS the wake signal — no separate Monitor needed (and arming one would cause double-wake on the same event). When watching external state (a CI job, a file change, a PR comment), arm a Monitor with persistent: true that fires on the matching event. Use a cron heartbeat ONLY as a fallback safety net for cases where the notification path might fail. Polling-as-primary-signal is an anti-pattern; the notification machinery exists for a reason.

  2. Cache-aware delay heuristic: 1200-1800s, never 300s. The Anthropic prompt cache has a 5-minute TTL. A loop firing every 4 minutes stays cache-warm but burns 12 cache loads per hour with no progress to show for it. A loop firing every 5 minutes pays one cache miss without amortising it (worst-of-both). The right cadences are under 270s (when actively watching something that's about to change — build finishing, log line about to fire) OR 1200-1800s (when there's no point checking sooner — fallback heartbeats, idle ticks). The 300-600s range is a trap: it feels reasonable in human time, but each fire pays a cold-cache penalty that dwarfs the work the wake actually does.

  3. Self-contained loop prompts: write for the future-you with no memory. The /loop prompt re-enters the session at each wake. It does NOT carry conversation context from the prior tick — only the prompt string and whatever is in memory files. Every loop prompt MUST be readable as a cron-message-to-future-self: complete subject, verb, object; no references to "the X we discussed"; explicit pointers to which files / which task ID / which wave to continue from. A prompt like continue M5 will fail at the next wake — the future-you doesn't know which wave, which task, or what "continue" means. A prompt like continue M5 Wave 1 dispatch — review pending subagent output, commit if green, dispatch next sequential task (T2→T3→T4 then Wave 2 5-way fan-out) works because every wake-up that reads it knows exactly what to do regardless of conversation state.

Evidence: First codified during Ratiba M5 Wave 1 dispatch (commit history starting at 871212b). The orchestrator dispatched T1 + filed an upstream issue in parallel (T0 ‖ T1), woke on the T1 subagent's completion notification, recovered the work after a transport-level subagent timeout, committed, and immediately dispatched T2. Wake-to-action latency from notification to next dispatch was under 60 seconds across all transitions in Wave 1. The pattern's non-obvious failure modes (stale prompts referencing completed work, redundant Monitors, tight polling) and worked examples are documented in appendix-k-loop-dispatch.md.

The /loop pattern interacts cleanly with the rest of the methodology:

  • The design artifact (Section 3.1) decides what to dispatch; /loop decides when.
  • Wave dispatch (Section 5.4) parallelises within a tick; /loop sequences across ticks.
  • Memory (Section 6) survives loop wake boundaries; conversation context does NOT.
  • STATE.md (Appendix J) is the orientation document the future-you reads at wake — keep it current at every commit so loop wakes have a non-stale entry point.