/cost-guardrail

name: cost-guardrail
description: LLM and cloud cost awareness — model tiering, token budgets, right-sizing, and when a cheaper model suffices. Trigger before finalising any architecture that calls LLMs, before scaling a workload, or when a cost estimate is needed.

Cost Guardrail

> **The most expensive model is the one running on every request when it does not need to.**

LLM cost is not a finance problem — it is an architecture problem. The design determines the bill. This skill enforces cost-awareness as a first-class design constraint, not an afterthought.

When to use

• Designing any system that calls an LLM (directly or via an agent)
• Before scaling a workload to higher volumes
• When a cost estimate is required for a feature or release
• When reviewing an architecture for unbounded cost vectors
• When choosing between model tiers for a given task

Procedure

1. **Identify every LLM call in the system** — list: which agent or component makes the call, the model tier used, the approximate input and output token counts, and the call frequency (per user action / per minute / per batch).

2. **Apply the model tiering test** — for each LLM call, ask:

• Does this task require deep reasoning, or is it classification / extraction / reformatting?
• Can the task be completed with a smaller or faster model?
• Is the model tier choice based on evidence (benchmark, A/B test) or assumption?

Starting hypotheses only (verify current pricing and qualify each task family before relying on them):

| Task type | Appropriate tier | |---|---| | Simple classification, extraction, summarisation | Small / fast model | | Complex reasoning, multi-step planning, code generation | Mid-tier model | | Deep analysis, architecture decisions, adversarial review | Highest-tier model |

A short ticket or one-file change does not qualify a cheap model. Require independent acceptance, preserve consequence floors, count failed attempts and bound escalation. Use the project's explicitly adopted routing mode; the [routing guide](references/model-routing.md) is not automatic consumer activation. Model/effort changes require a fresh baseline.

3. **Identify unbounded cost vectors** — flag any call pattern where the token count or call volume has no upper bound:

• Loops that call an LLM until a condition is met (with no max-iteration guard)
• User-triggered calls with no rate limiting
• Context windows that grow unboundedly across a conversation
• Batch jobs with no per-run budget ceiling

4. **Estimate the monthly cost envelope** — for each LLM call:

   estimated monthly cost ≈ ((input tokens/call × input price) + (output tokens/call × output price)) × calls/month

Use current published rates from your provider. Do not use rates from training data — they change.

5. **Add cost controls** — for each unbounded vector:

• Set a max-token budget per call (trim context if needed)
• Add rate limiting at the application layer
• Add a budget alert at the infrastructure layer
• Consider caching repeated calls with identical or near-identical inputs

6. **Check for caching opportunities** — LLM calls that return the same result for the same input are cacheable. Prompt caching (where supported by the provider) can reduce cost significantly on repeated prefixes.

7. **Document the cost model** — in the ADR or design doc, record: model tiers chosen, rationale, estimated monthly cost at target scale, and the controls in place.

Outputs

For engineering-agent routing, use the task/effort matrix in [`council.md`](../pr-reviewer/references/council.md). Declare requested and resolved model, reasoning, bounded inputs, timeout, retry ceiling and acceptance test per lane. Measure total time/known cost to accepted outcomes including review and rework; unknown usage is not zero. Start with the smallest proven capable model, escalating on observed failure or ambiguity while preserving the quality and independence floor.

• LLM call inventory: component | model tier | input tokens (est.) | output tokens (est.) | frequency | monthly cost (est.)
• Unbounded cost vectors flagged with mitigations
• Monthly cost estimate at target scale
• Recommended model tier per call with rationale

Guardrails

• **Never use pricing from training data.** Rates change. Fetch current rates from the provider's documentation before estimating.
• **A call that "works" at low volume may be unaffordable at scale.** Always estimate at the target scale, not the current scale.
• **Caching is not optional for high-frequency repeated calls.** An uncached LLM call repeated thousands of times per day is a design flaw.
• **Token budgets are architecture decisions.** Decide them explicitly; do not let the model decide by consuming whatever context is available.

Anti-rationalization table

| Excuse | Counter | |---|---| | "It's only a few cents per call" | At scale, cents become thousands of dollars. Estimate the monthly envelope. | | "We'll optimise later" | Cost optimisation is hardest after the architecture is set. Do it now. | | "The big model gives better results" | Verify with a test. Small models are often sufficient for structured tasks. | | "We don't know the volume yet" | Estimate a range. A 10x cost swing between low and high volume is a design risk. |