Credit and Cost Control

Forecast before spending, ceiling everything, and compare providers on cost per usable record rather than on price.

When to use

• Before any enrichment, research, or agent run at scale
• The bill arrived larger than expected
• Choosing between providers
• Setting up access for a new user, which is the highest-risk moment

Inputs

• Needs from user: current balance, the run definition, provider pricing, and who has access to spending keys
• Reads: workspace/data/waterfall-spec.csv

Workflow

1. Run the pre-flight

Every time. This is a hook-worthy checklist, meaning it should be enforced by the tool rather than remembered by a person.

[ ] Current balance checked and recorded
[ ] Estimated cost of this run computed and stated out loud
[ ] Free and known-field gate confirmed upstream of every paid column
[ ] Row cap set on this run
[ ] Enrich-only-empty-fields confirmed
[ ] Deep or exhaustive research modes off unless explicitly approved
[ ] Account-level ceiling configured and current
[ ] Test at 5 rows completed and inspected

If the estimate exceeds 20% of the remaining balance, stop and get a decision. Do not proceed and report afterward.

2. Forecast the run

Rows after the gate            n
× expected cost per row        from the waterfall arithmetic
= estimated spend              n
÷ expected usable records      n
= forecast cost per usable     n

State all five numbers before starting. A forecast you did not write down is not a forecast.

3. Compare providers correctly

Price per lookup is the wrong comparison. Build the table.

A provider at 40% of the price with 30% of the match rate is more expensive per usable record and delivers a much smaller list. Run the table on your own segment, because match rates vary enormously by geography and company size.

4. Install ceilings that fail closed

Three layers, and the third is the only one that actually holds.

Per-user keys with per-user ceilings. A shared key with no per-user limit is one bad afternoon away from the month's budget. This is the single most common expensive mistake, and it is a five-minute fix.

5. The 5/25 pattern

Test on 5 rows. Inspect the output field by field. Then 25. Inspect again. Then release to the capped run.

This catches nearly everything a full run would have taught you, at a fraction of a percent of the cost. The failures it catches are usually a wrong field mapping, a provider returning the wrong entity, or a prompt producing plausible fabrication.

6. Monthly review, four numbers

1. Total spend by layer, and the trend
2. Cost per usable record by pipeline, three-month trend
3. Correction rate per deployed agent
4. Utilization: what fraction of what you bought was used

Number four kills more contracts than the other three combined. Seat-based and credit-based tools are routinely bought a tier above real consumption and nobody checks, because the invoice is a fixed line item. Check it sixty days before renewal.

Output

• Writes: workspace/data/cost-model.csv, run log with actuals against forecast
• Uses: templates/cost-model.csv
• Prints: the pre-flight result, the five forecast numbers, actual against forecast after the run, and any ceiling changes made

Rules & quality bar

• Pre-flight before every run that costs money
• State the forecast before starting, and compare actual to forecast afterward
• Cost per usable record is the only provider comparison that counts
• Ceilings at the account level, per user. Advisory budgets do not hold
• 5 rows, then 25, then release
• Deep research modes default off
• Never run unbounded. Every run has a row cap
• Estimate over 20% of remaining balance means stop and ask

Related skills

• Pairs with: enrichment-waterfall, agent-guardrails
• Informs: martech-stack-audit at renewal
• See also: docs/cost-model.md for the full arithmetic and failure modes