---
name: loop-budget
description: Guards an autonomous loop against runaway token and time spend with daily caps, report-only mode, and kill-switches. Use when a loop runs unattended, when API costs must stay bounded, or when a cycle should degrade gracefully to reporting instead of acting.
category: loop-engineering
keywords: budget, token-limits, kill-switch, cost-control, guardrails
---

# Loop Budget Guard

## When to apply

Run at the **start and end of every loop iteration** whenever the loop spends tokens, money, or wall-clock time unattended. Budgets turn "run forever chasing a flaky test" into "stop, report, and let a human decide".

## Configuration file (`loop-budget.md`)

```markdown
# daily caps per pattern, in estimated tokens
triage: 50k
bugfix: 200k
refactor: 400k
# kill switches (any true → immediate exit)
loop-pause-all: false
```

## Start of run

1. Read `loop-budget.md` for caps and kill-switch flags.
2. Read the last 24h of `loop-run-log.md` entries; sum `tokens_estimate` per pattern.
3. Spend ≥ 80% of a pattern's cap → **report-only mode**: no sub-agents, no auto-fix; observations only.
4. Spend ≥ 90% with high-priority items still open in the state file → negotiate (downscope, or ask a human to raise the cap).
5. Spend ≥ 100%, or any kill-switch set → **exit immediately** with a one-line note in the state file.
6. Nothing actionable in the watchlist → exit in under 5k tokens. Do not spawn sub-agents to "look busy".

## End of run

Append one JSON line to `loop-run-log.md`:

```json
{"ts":"2026-08-20T14:03:00Z","pattern":"bugfix","tokens_estimate":12300,"outcome":"fixed|partial|blocked|no-op","items":["slug-1"]}
```

## Rules

- Estimates are fine; honesty about estimates is mandatory. When unsure, round up.
- Report-only mode still writes the log — data collected cheaply today budgets tomorrow correctly.
- Never delete log lines to "reset" a budget; that's the spend problem wearing a different hat.

## Related skills

- [loop-constraints](/skills/loop-constraints) — The safety rules layer that complements spending caps.
- [loop-triage](/skills/loop-triage) — Decides what's worth spending the budget on.