Choose Loop Wakeup Interval

Pick delaySeconds for ScheduleWakeup. Respect prompt cache 5-minute TTL, scheduler whole-minute granularity, [60, 3600] runtime clamp. Instinct "wait about 5 minutes" lands in worst-of-both zone — pay cache miss without amortizing wait.

Reasoning travels with ScheduleWakeup tool description at call time, but by then loop already scheduled. This skill hoists reasoning to planning time, where it belongs.

When Use

• Designing autonomous /loop or ScheduleWakeup-driven continuation. Pick per-tick delay.
• Planning heartbeat cadence for long-running agent. Poll, watch, iterate.
• Tuning polling cadence against cost or cache-warmth pressure
• Post-hoc review of loop costs → interval mis-sized
• Writing guide, runbook, worked example involving delaySeconds

Inputs

• Required: What loop waits for (specific event, state transition, idle tick, periodic check)
• Required: Next tick needs fresh context (cache-warm)? Or cold re-read OK (cache-miss acceptable)?
• Optional: Known lower bound on when awaited event could occur (e.g., "build takes at least 4 minutes")
• Optional: Cost ceiling on total loop (ticks × per-tick cost)

Steps

Step 1: Classify the Wait

Pick tier:

• Active watch (cache-warm): something expected to change within 5 minutes — build nearing completion, state transition polled, process just kicked off
• Cache-miss wait: nothing worth checking sooner than 5 minutes; context cache goes cold, acceptable
• Idle: no specific signal; loop checks in because might find something, not because will

Got: Clear classification: active-watch, cache-miss, or idle.

If fail: Cannot classify? No honest answer to "what am I waiting for?" → loop probably should not exist. Skip to Step 5. Consider not scheduling at all.

Step 2: Apply the Three-Tier Decision

Pick delaySeconds from classification:

Tier	Range	Cache behaviour	Use when
Cache-warm	60 – 270 s	Cache stays warm (under 5-minute TTL)	Active watch — next tick needs fast, cheap re-entry
Cache-miss	1200 – 3600 s	Cache goes cold; one miss buys long wait	Genuinely idle, or awaited event cannot happen sooner
Idle default	1200 – 1800 s (20–30 min)	Cache goes cold	No specific signal; periodic check, user can interrupt

Do not pick 300 s. Worst-of-both interval: cache misses, but wait too short to amortize miss. Reaching for "about 5 minutes"? Drop to 270 s (stay warm) or commit to 1200 s+ (amortize miss).

Got: Specific delaySeconds from one of three tiers. Not round-number-minute picked from habit.

If fail: Choice keeps landing on 300 s? Underlying question: "should this loop exist at this cadence at all?" Re-examine Step 1.

Step 3: Size for the Minute Boundary

Scheduler fires on whole-minute boundaries. delaySeconds of N produces actual delay of N to N + 60 s. Depends on what second of minute you call tool.

Worked example:

ScheduleWakeup({delaySeconds: 90}) at HH:MM:40 → target HH:(MM+2):00. Actual wait 140 s, not 90 s.

Consequence: sub-minute intent meaningless. Treat value as floor, not precise schedule. If minute of skew matters, loop cadence too tight for this mechanism.

Got: Accepted: actual wait up to 60 s longer than requested delaySeconds. Cache-warm ticks affected — 270 s can become ~330 s in practice, tipping into cache-miss territory.

If fail: Near-ceiling values (e.g., 265 s targeting cache-warmth) common? Pad downward. Use 240 s instead of 270 s. Preserves cache-warm guarantee under worst-case skew.

Step 4: Respect the Clamp

Runtime clamps delaySeconds to [60, 3600]. Outside range silently adjusted. Telemetry distinguishes chosen_delay_seconds from clamped_delay_seconds. Sets was_clamped: true on mismatch.

Plan against clamped value, not requested:

• Request below 60 → actual wait 60 s plus minute-boundary skew (up to 120 s in practice)
• Request above 3600 → actual wait 3600 s (1 hour)
• No runtime extends ceiling. Multi-hour waits require multiple ticks.

Got: Chosen value falls inside [60, 3600]. Or clamped behaviour deliberately accepted.

If fail: Need genuinely multi-hour (e.g., "wake me in 4 hours")? Chain wakeups — schedule 3600 s tick that reschedules itself. Or use cron-based loop (CronCreate with kind: "loop").

Step 5: Write a Specific reason

reason field = telemetry + user-visible status + prompt-cache warmth reasoning. One line. Truncated to 200 chars. Make specific.

• Good: checking long bun build, polling for EC2 instance running-state, idle heartbeat — watching the feed
• Bad: waiting, loop, next tick, continuing

Reader: user trying to understand what loop is doing without predicting cadence in advance. Write for them.

Got: Concrete, one-phrase reason. Makes sense to user glancing at status.

If fail: No specific reason available? Revisit whether loop should exist (Step 1, Step 6).

Step 6: Recognize the Don't-Loop Case

Not every "come back later" impulse warrants scheduled wakeup. Do NOT schedule tick when:

• User actively watching — their input is right trigger, not timer
• No convergence criterion — loop has no definition of "done"
• Task interactive (asks user questions between ticks)
• Cadence shorter than clamp floor (60 s) — polling that tight belongs to event-driven mechanism, not loop

Got: Conscious choice between scheduling wakeup and not looping. "Because I could" not a reason.

If fail: Keep scheduling wakeups user interrupts before they fire? Pattern is wrong — not interval.

Checks

• Wait classified as active-watch, cache-miss, or idle
• Chosen delaySeconds falls in one of three tier ranges (60–270, 1200–3600, or 1200–1800 for idle)
• Value is not 300 (worst-of-both)
• Value inside [60, 3600] or clamped behaviour explicitly accepted
• Minute-boundary skew accounted for (value as floor)
• reason concrete, under 200 chars
• Don't-loop check performed — wakeup actually warranted

Pitfalls

• Round-minute default (300 s): Single most common mistake. "About 5 minutes" feels natural, exactly wrong. Drop to 270 s or commit to 1200 s+.
• Ignoring minute-boundary skew: Request 60 s near end of minute → ~120 s actual delay. Cache-warm ticks: can push past 5-minute TTL.
• Chasing sub-minute precision: Scheduler has minute granularity. 85 vs 90 vs 95 s is noise. Pick value, move on.
• Opaque reason fields: "waiting" tells user nothing. Telemetry useless. Write reason as if user reads it on status line.
• Using this skill to justify unnecessary loop: Honest answer to "what am I watching for?" vague? No interval choice helps. Loop should not exist.
• Hand-clamping in prompt: Do not clamp in model reasoning ("I'll cap at 3600 to be safe"). Runtime clamps. Let it.
• Forgetting 7-day age-out: Dynamic loop reaped after 7 days default (user-configurable up to 30). Long loops designed to end well before ceiling, not race it.

Examples

Example 1 — Cache-warm active watch

bun build kicked off. Agent wants to check in quickly, cache still warm when results arrive.

• Classification: active watch (Step 1)
• Tier: cache-warm (Step 2), pick 240 s
• Minute boundary (Step 3): worst-case actual wait ~300 s — still under 5-minute TTL with 60 s buffer
• Reason (Step 5): checking long bun build

Example 2 — Idle heartbeat

Autonomous agent watches low-volume feed once an hour for anything worth acting on.

• Classification: idle (Step 1)
• Tier: idle default (Step 2), pick 1800 s (30 min)
• Minute boundary (Step 3): irrelevant — 60 s skew negligible at this cadence
• Reason (Step 5): idle heartbeat — watching the feed

Example 3 — The anti-pattern

Agent wants to "wait 5 minutes" while remote API retries. Request is 300 s.

• Problem: cache goes cold at 5 minutes. 300 s pays miss — but 300 s too short to amortize miss.
• Fix: drop to 270 s (stay warm) or commit to 1500 s (amortize miss). Do not pick 300.

See Also

• manage-token-budget — cost ceilings for long-lived agent loops; cache-aware sizing one lever
• du-dum — observe/act separation pattern; sizes observe-clock interval when loop is cron-less
• read-continue-here — cross-session handoff; this skill covers within-session wakeups
• write-continue-here — complement of read-continue-here

<!-- Keep under 500 lines. Current: ~200 lines. -->