cost-estimation

Cost Estimation

Estimate, before work runs, the token usage and time a task will consume flowing through the orchestrator pipeline — and a dollar cost only when observed actuals exist to ground it.

This is the prospective counterpart to the retrospective cost-tracking skill. cost-tracking records what was spent into observability/costs/YYYY-MM-DD-costs.md; this skill reads those same snapshots as its $/token ground and predicts what a task will spend. The two are siblings — a reader who finds one should find the other (see Sibling relationship).

The day-one deliverable is a token + time estimate. Both axes are fully groundable from MODEL_ROUTING.md today, so they are the honest first-version value of this capability. The dollar figure is an actuals-gated enhancement — present and grounded only when an observability/costs/ snapshot supplies a usable $/token rate, otherwise omitted with an explicit disclosure (never a forced list-price guess).

This skill is methodology and a format contract. It describes how an estimate is derived and what an estimate record must contain. It does not dispatch an agent, write a file, or decide go/no-go — see What this skill does NOT do.

An Estimate Is a Range, Never a Point

The material decision this skill locks: an estimate is a range with disclosed confidence, never a point value.

A point value invites false precision. "12k tokens" reads as fact; "10k–18k tokens, confidence medium, more likely to overrun than underrun because the implementer stage spans two model tiers" reads as a prediction a human can interrogate. The whole point of the capability is to inform a human's choice, not to anchor it on a number dressed as a fact.

Every quantitative field is therefore a { low, high } range, and every record carries per-axis confidence and the disclosures the contract requires. The canonical field definitions live in the format reference:

Format reference: references/estimate-record-format.md — the stable estimate-record field set, the tier→model→$/token binding table, the four-part disclosure body, the validation checklist, and two worked examples. A downstream command's Output Validation Checkpoint references that file by path.

Grounding Methodology

The grounding sources are fixed, not chosen — the methodology names them, it does not offer a choice between them. Token ranges and agent-compute time are always groundable from MODEL_ROUTING.md. The dollar figure is groundable only when a snapshot supplies a usable $/token rate; otherwise it is omitted. Human-gate time is not estimated numerically at S1.

Token derivation from MODEL_ROUTING.md

MODEL_ROUTING.md carries two tables the methodology consumes:

• Token Budget Guidance — per-role ranges: spec-writer 50–100k, tdd-agent 50–150k, implementer 100–250k, code-reviewer 50–100k, integration-agent 30–80k. Each role's low–high becomes that stage's tokens range.
• Agent Routing — the agent→model-tier mapping (orchestrator, spec-writer, advocatus-diaboli → Most capable; tdd-agent, integration-agent → Standard; implementer → Standard / Capable; code-reviewer → Most capable). Each stage's model_tier is read from this table.

The per-stage token ranges sum into the whole-record tokens range (stages may be correlated, so the whole-record range need not equal the arithmetic sum — when they differ the prose body must say why). Which stages a target exercises depends on target_kind: a docs-only spec may exercise spec-writer + review only, and the omitted stages must be disclosed in Excluded.

Split-tier stages. The implementer stage maps to a split tier Standard / Capable ("Depends on task complexity"), and it carries the largest token budget (100–250k), so its rate dominates any cost figure. The methodology does not leave the tier choice to agent discretion. A split-tier stage is priced (when cost is computed at all) by widening its cost contribution to span both ends of the split: its low bound uses the cheaper end (claude-sonnet-4, the Standard representative) and its high bound uses the dearer end (claude-opus-4, the Most capable representative — the tier the split rises to for complex tasks, since MODEL_ROUTING.md carries no standalone Capable model). Because the two ends bind to different representative models, the widening produces a genuine spread for this dominant stage rather than collapsing to one rate. The tokens_by_stage[].model_tier field records the literal split label (Standard/Capable) so the breakdown stays traceable.

Cost derivation — only when a snapshot grounds it

cost_usd is present only when an observability/costs/ snapshot supplies a usable per-tier $/token rate. Deriving that rate requires a named binding, because MODEL_ROUTING.md tiers are abstract labels with no model or price, while the snapshot's Model Breakdown is keyed by model name. The binding is fixed in the format reference's tier→model→$/token binding table:

Model tier (MODEL_ROUTING)	Representative model family stem
Most capable	claude-opus-4
Standard	claude-sonnet-4
Standard / Capable (split)	spans claude-sonnet-4 (low) … claude-opus-4 (high), widened

MODEL_ROUTING.md names exactly two tiers — Standard and Most capable — and one complexity-dependent split, the implementer's Standard / Capable. There is no standalone Capable tier with its own model; the dearer end of the split resolves to Most capable.

Family resolution, not exact keys (v0.50.0). A snapshot Model Breakdown key resolves to a tier's representative by family stem — it matches iff it starts with the stem and the next character is - or end-of-string (so claude-opus-4 resolves the real id claude-opus-4-8, but not claude-opus-40). Multiple rows in one family aggregate into one blended rate (disclosed when >1). This is the #411 fix: a snapshot keyed by the actual model id now grounds cost where the old exact-string match silently omitted it. The full rule (delimiter, aggregation, and the cross-tier proxy for a tier whose family is absent) lives in the format reference's binding table — this skill does not restate it.

Deriving a per-model rate from a snapshot. The snapshot's ## Model Breakdown table gives, per model, quarter-aggregate input/output token volumes and an estimated cost. The methodology computes a per-model $/token as estimated_cost ÷ (input_tokens + output_tokens) — a single blended rate per model. The binding table maps each stage's tier to its representative model's blended rate, and cost_usd = Σ over stages (stage tokens range × tier $/token), with split-tier stages widened as above.

Per-stage cost_usd bands (cost-present records only). When a record is cost-present (state 3 below), the emitter also surfaces the per-stage decomposition that produced the whole-record figure: each exercised stage carries a tokens_by_stage[].cost_usd { low, high } band (the stage's tokens range × its tier rate), with split-tier stages priced low at the cheaper representative model and high at the dearer one so the spread is strictly positive (low < high). This follows the format reference's per-stage band pricing convention — an emitter obligation (a SHOULD), not a validation-rejection rule, and not a new derivation. On a cost-omitted record no stage carries the sub-field (the coupling is one-directional: a per-stage band never appears without the top-level cost_usd).

The grounding states (four, under family resolution — v0.50.0). The snapshot's Model Breakdown is marked "(if available)" in the cost-tracking format, and binding resolves tiers by family stem (above), so the methodology branches on four states. The canonical statement is the format reference's "grounding states for cost"; in brief:

1. No snapshot exists — observability/costs/ is empty. → cost_usd omitted, disclosed in Excluded.
2. Snapshot exists but the Model Breakdown is absent or too coarse to yield a per-tier rate. → cost_usd omitted, disclosed naming this specific cause ("a cost snapshot exists but carries no usable per-model breakdown"). The methodology does not fall through to list price.
3. Snapshot present but NO estimating-tier family resolves — after family resolution, neither the claude-opus-4 nor the claude-sonnet-4 family is present (e.g. a haiku-only snapshot). → cost_usd omitted, naming the cause. (This is the family-resolution successor of the old "missing model key" omission.)
4. Snapshot present with ≥1 estimating-tier family resolving → cost_usd present, confidence.cost from the snapshot's age/granularity, snapshot date/quality disclosed in Included. The basis distinguishes two cases: every exercised tier's family resolves directly → cost_basis: snapshot-actuals; at least one exercised tier's family is absent and is priced by the cross-tier proxy (binding table) → cost_basis: snapshot-actuals-proxied, with failure_direction: likely-overrun and confidence.cost: low forced and every proxied tier disclosed.

There is no list-price fallback. A list-price guess is not an observed cost; emitting it as a first-class figure was the false precision this methodology opposes. When cost cannot be grounded in actuals, it is omitted with disclosure, and the day-one deliverable remains the token + time estimate.

The no-cost case is honest, not a failure. When cost_usd is omitted (states 1–3), the record is valid and complete — it is the expected day-one shape. The Excluded section carries an explicit omission disclosure, e.g.:

"cost_usd: omitted — no repo cost snapshot exists yet, so no observed $/token is available; cost is not estimated. Token and time figures stand."

A grounded token + time estimate plus an honest "dollars are not yet knowable" is more informative than a low-confidence list-price range that says "we don't really know" in numeric clothing. No format change is required when the first snapshot lands — the same cost_usd/cost_basis/confidence.cost fields simply begin to appear. This is the seam the calibration loop now closes.

The Disclosure / Confidence Contract

This four-part disclosure body is a contract this skill proposes — it is not a pre-existing promoted AGENTS.md decision. It serves the real AGENTS.md "agent-emit + dispatcher-persist + human-disposes" trust architecture: a research-and-author agent emits content and the human disposes. The disclosure contract makes the derivation interrogable so the human's disposition is informed. An estimate record that does not satisfy this contract is invalid regardless of how good its numbers are.

Mandatory four-part disclosure body

Every estimate record's prose body MUST contain four labelled sections:

1. Included — what the estimate counts, and the provenance/quality of each included input. Caveats about the quality of an included input (an assumed compute band, a snapshot of a given age) live here or under Confidence rationale, never under Excluded.
2. Excluded — what the estimate does NOT count, stated plainly: human-gate latency (excluded from cost_usd and tokens because gates cost wall-clock not tokens); re-runs and diaboli/cartograph cycles beyond one pass; any stages a target does not exercise. When cost_usd is omitted because no usable snapshot rate exists, that omission is disclosed here. Excluded items are the single most important honesty signal — a number that silently omits a cost class is worse than no number.
3. Confidence rationale — why each confidence axis (tokens, time, and, when present, cost) is what it is, tied to the target_kind and the grounding richness.
4. Failure direction — a one-line statement matching the failure_direction field, naming WHY the estimate is more likely wrong in that direction. This section describes uncertainty only — it must contain no imperative recommendation and no go/no-go language.

A record missing any of the four sections fails validation.

Per-axis confidence

Confidence is recorded per axis (tokens, time, and — only when cost_usd is present — cost), not as one whole-record tier. The tokens/time axes have a ceiling tied to target_kind; the cost axis has its own independent rule.

• Target-kind ceiling (tokens/time): task-text caps at low; slicing-record/slice at most medium; spec may reach high. The ceiling is a cap, not a verdict — an axis may sit below it, but a raw-text estimate's token confidence can never be high.
• Cost axis (independent): exists only when cost_usd is present. Set from the snapshot's quality (age, breakdown granularity), and independent of target_kind — a spec-grounded target with a stale snapshot can carry tokens: high beside cost: low without contradiction.

The time axis describes confidence in the agent_compute_time estimate only — human_gate_time carries no numeric estimate at S1, so there is no human-gate number for the time axis to qualify.

Confidence is disclosed, never decisive — the two-layer no-verdict guarantee

The record carries confidence; it does not carry a verdict, recommendation, or go/no-go. The human reads the ranges and disclosures and decides. This guarantee has two layers of differing strength:

1. Field-absence layer (structural) — there is no recommendation, verdict, or proceed field. This layer IS a property of the format itself, independent of any agent's behaviour: a field that does not exist cannot carry a verdict. (Necessary but not sufficient: a verdict could be smuggled into free-text prose.)
2. Positive-content layer (tripwire, not proof) — the four disclosure sections describe inputs and uncertainty only. They MUST NOT contain imperative recommendation or go/no-go language. A validation check scans the disclosure prose for prohibited patterns ("so proceed", "do not proceed", "I recommend", "you should [ship|skip|approve|reject]", "go/no-go") and fails the record if any appear. A "failure direction: likely-overrun, so do not proceed" sentence fails this check even though it passes field-absence. But this scan is a closed enumeration of common verdict phrasings — a tripwire, not a proof: a paraphrased verdict ("the high bound makes this not worth building") can evade the listed patterns. Its strength is "catches the common cases", not "independent of any agent's behaviour".

The field-absence layer is a structural guarantee; the positive-content layer catches the common cases and leans on the agent not paraphrasing around the list. The enumerated checks live in the format reference's validation checklist.

The Time Split

agent_compute_time and human_gate_time are two separate required fields with different shapes:

• agent_compute_time is the wall-clock the model spends generating — the predictable term. It is derived from token volume by applying a disclosed tokens→wall-clock band (the reference fixes a default, e.g. "~1–3 min per 10k tokens generated") to the tokens range, yielding a numeric { low, high } range. The band is stated as an assumption in Included; it is not claimed to be an observed actual.
• human_gate_time is the wall-clock spent waiting for a human at the orchestrator's disposition gates. It dominates total wall-clock and is the least predictable term — it depends on when a human next sits down, not on the work itself. It is not estimated numerically at S1: it is a disclosed qualitative caveat string, not a range. Its grounding — the orchestrator gate set and how many gates a target passes through — lives in the orchestrator (S4), which this slice does not touch. Multiplying an ungrounded gate count by a per-gate band would re-introduce the very false precision the range-not-point decision exists to prevent.

Collapsing the two into one number would hide the dominant source of variance. The failure-direction prose must reference this: an estimate whose wall-clock omits human-gate latency is likely-underrun on wall-clock unless the human-gate caveat is read alongside it.

The Calibration Loop (S6)

The calibration loop is implemented (slice S6). The integration-agent captures a per-PR actuals record at merge time — defined in cost-tracking/references/per-pr-actuals-format.md and written to observability/costs/per-pr/ — and this methodology reads the accumulated records to refine estimates against this repo's own history. True to the seam S1 promised, calibration ships with no format change: it is the already-permitted kind: calibration grounding_sources[] entry plus a disclosure, nothing more.

What calibration refines — token ranges only. Calibration narrows the per-stage token ranges toward the observed history and, when enough records exist for a stage, raises the tokens confidence one tier (never above the target_kind ceiling). It does not touch cost_usd or cost_basis: the $/token ground stays the snapshot (cost_basis: snapshot-actuals), and a per-PR record's dollar figure — when present at all — is not promoted to a rate. This is the deliberate token-ranges-only reach.

How the records are read:

• Glob observability/costs/per-pr/ for actuals records. For each stage, gather the supplied per-stage token actuals (tokens_by_stage[].tokens that are numbers, not the literal unavailable) across the accumulated records and use their central tendency to narrow that stage's range.
• A record whose figures are unavailable still contributes its structural signal: its stages_run tells you which stages this repo actually exercises, so a stage the repo never runs can be dropped (disclosed in Excluded). unavailable is not zero — it never pulls a token magnitude down.
• Add a kind: calibration grounding_sources[] entry naming the per-pr/ directory, and disclose the basis in Confidence rationale — how many records informed the narrowing and over what date range (e.g. "token ranges narrowed against 9 per-PR actuals, 2026-06 to 2026-08; cost unchanged — calibration refines tokens only").

Zero history is the valid day-one state. When observability/costs/per-pr/ is absent or empty, the methodology behaves exactly as it did before S6: generic MODEL_ROUTING.md budgets, no calibration entry, no calibration disclosure. The loop degrades cleanly to the pre-S6 behaviour.

Calibration never overrides the disclosure contract. A calibrated estimate is still a range with disclosed confidence and a stated failure direction. Calibration can narrow a range and raise its confidence; it can never collapse a range to a point or suppress the Excluded/Confidence rationale disclosures.

Sibling Relationship to cost-tracking

The cost-estimation skill is the prospective counterpart to the retrospective cost-tracking skill. The two reuse the same observability/costs/ data:

• cost-tracking writes the snapshots (via /cost-capture).
• cost-estimation reads them as its $/token ground.

/cost-capture records what was spent; the future /cost-estimate predicts what will be spent. A user who knows one half of the cost capability should discover the other from either skill's description.

What This Skill Does NOT Do

• Does not dispatch an agent. The read-only cost-estimator agent that emits a record is a downstream consumer, not this skill.
• Does not write files or run a command. Writing and validating a record is a downstream command's job; this skill defines what such a record must contain.
• Does not wire into the orchestrator. No gate is added, moved, or re-weighted by this skill; the orchestrator fold-in lives in the orchestrator agent (T0/T1/T2).
• Does not capture calibration actuals. This skill defines the calibration methodology (how per-PR actuals refine token ranges), but the per-PR actuals are written by the integration-agent and the format is owned by cost-tracking — this skill only reads them.
• Does not decide go/no-go. It emits ranges and disclosures for a human to dispose; it carries no verdict, recommendation, or recommendation prose.