rshade/finfocus / agent-skills/cost-drift
cost-drift
UnverifiedCompare actual and projected spend for a Pulumi stack with the FinFocus CLI, flag drifting resources against thresholds in .cost-check.yml, explain likely causes, track the trend, and write a COST_DRIFT.md report. Reads machine-readable JSON, checks the CLI version, and names what to do when the CLI, a billing plugin, credentials, or a Pulumi preview is missing. Use when investigating a cost overrun, validating projections against reality, or watching spend drift in CI. Triggers on: "cost drift", "actual vs projected", "why is spend higher than expected", "drift report", "COST_DRIFT.md".
Cost Drift
Run finfocus overview on a Pulumi stack, flag resources whose actual spend
has moved away from the projection, and write COST_DRIFT.md.
Install: npx skills add rshade/finfocus -s cost-drift.
Required CLI: finfocus v0.5.0 or newer. Update this line with the release the skill was last run against.
Core principle: use the drift the CLI computes. Do not query billing APIs,
and do not turn a missing costDrift into "no drift".
overview accepts Terraform plan and state JSON. For a Terraform
project, run the cost-check skill and say that drift is not available. Edit
this paragraph when that changes.
1. Detect the project
Look for Pulumi.yaml or Pulumi.yml in this directory or a parent. If there
is none, stop: "No Pulumi project detected."
2. Preflight
command -v finfocus
finfocus --version
finfocus plugin list --output json
- No binary: stop and point to the
finfocus-installskill. - Version below the required one: stop and print both versions. A build such
as
v0.5.0-6-g3cb7dedcounts as v0.5.0. An unparseable version, or0.1.0with no leadingv(an unstamped source build), continues, and the report says "version unverified". - No plugin whose
capabilitiesincludeactual_costs: stop. Drift needs a plugin that returns billing data. Point tofinfocus-install.
Every failure and its handling: references/failure-modes.md.
3. Load thresholds and baseline
Read the drift: section of .cost-check.yml. Absent keys use the defaults:
references/thresholds.md. If a previous
COST_DRIFT.md exists, keep its drifting-resource count and actual total for
the trend.
4. Run the CLI
finfocus overview --output json --yes
finfocus overview --output json --yes --stack <stack> --from 2026-10-01
finfocus overview --output json --yes --state-only
By default overview runs pulumi stack export and pulumi preview --json.
--state-only skips the preview. --pulumi-state and --pulumi-json use
files the user already has. Keep stdout and stderr apart and record the exit
code. Fields and exit codes: references/cli-contract.md.
5. Validate before trusting the numbers
- Exit
0, or a budget exit (error_codebudget_exceeded) with a JSON document on stdout. Record the budget breach in the report and keep going: an overrun is when drift matters most. Any other exit: stop witherror_codeandmessage. errorsis empty, or each entry is listed in the report.- At least one row has
actualCost. If none does, stop withno-actualsand point tofinfocus-diagnose. A presentactualCostdoes not prove billing data: when a plugin returns0with no breakdown, the CLI substitutes the projected hourly rate times uptime, and the overview JSON drops the adapter, confidence and notes that would show it. Never call the figures billing-backed. Print "Billing verification: unavailable" in the summary and the report, and readPASSas "no drift flagged against the CLI's figures". - A row has drift only when it carries
costDrift. The CLI leavescostDriftout when the drift is within 10%, when the resource is new or deleted, and when less than 2 days of the window have elapsed. Report those rows as "within 10%", "new or deleted", or "insufficient data". Never as zero drift.
6. Flag
Read each row's costDrift:
abs(percentDrift)abovedrift_pct.abs(delta)abovedrift_absolute.
There is no overall drift figure. The CLI measures each row from its real start, and the summary totals cannot be compared fairly (see references/thresholds.md).
Overspend and underspend both count. drift_pct below 10 cannot flag more
than the CLI reports, and the report says so when the user set one.
7. Explain
For each flagged row, match type to
references/drift-explanations.md. Pick
overspend when delta is above 0, underspend when below. Use the fallback for
types that are not listed. Each entry gives a likely cause and an
investigation step.
8. Report
Print the drifting-resource count, the trend against the previous check, and
each flagged resource with actual, projected, delta, drift, cause, and next
step.
Write COST_DRIFT.md from
references/report-template.md. Run
markdownlint COST_DRIFT.md when the tool is installed.
End with one line CI can match:
COST_DRIFT_RESULT: PASS | DRIFTING | ERROR (<kind>)
Then ask whether to investigate a resource or adjust thresholds.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |