cost-drift
Compare 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 wha
Install
npx skills add https://github.com/rshade/finfocus/tree/main/agent-skills/cost-drift
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install rshade-finfocus@llmmart
git clone https://github.com/rshade/finfocus.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole rshade/finfocus collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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.
Files (finfocus)
-
references
-
cli-contract.md 3.2 KB
Loading… -
drift-explanations.md 4.6 KB
Loading… -
failure-modes.md 2.3 KB
Loading… -
report-template.md 1.9 KB
Loading… -
thresholds.md 2.6 KB
Loading…
-
-
cost-drift.skill 9.8 KB · in bundle
-
SKILL.md 5.3 KB
--- name: cost-drift description: > Compare 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". --- <!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. --> <!-- SPDX-License-Identifier: Apache-2.0 --> # 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 ```bash command -v finfocus finfocus --version finfocus plugin list --output json ``` - No binary: stop and point to the `finfocus-install` skill. - Version below the required one: stop and print both versions. A build such as `v0.5.0-6-g3cb7ded` counts as v0.5.0. An unparseable version, or `0.1.0` with no leading `v` (an unstamped source build), continues, and the report says "version unverified". - No plugin whose `capabilities` include `actual_costs`: stop. Drift needs a plugin that returns billing data. Point to `finfocus-install`. Every failure and its handling: [references/failure-modes.md](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](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 ```bash 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](references/cli-contract.md). ## 5. Validate before trusting the numbers 1. Exit `0`, or a budget exit (`error_code` `budget_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 with `error_code` and `message`. 2. `errors` is empty, or each entry is listed in the report. 3. At least one row has `actualCost`. If none does, stop with `no-actuals` and point to `finfocus-diagnose`. A present `actualCost` does not prove billing data: when a plugin returns `0` with 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 read `PASS` as "no drift flagged against the CLI's figures". 4. A row has drift only when it carries `costDrift`. The CLI leaves `costDrift` out 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`: 1. `abs(percentDrift)` above `drift_pct`. 2. `abs(delta)` above `drift_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](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](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](references/report-template.md). Run `markdownlint COST_DRIFT.md` when the tool is installed. End with one line CI can match: ```text COST_DRIFT_RESULT: PASS | DRIFTING | ERROR (<kind>) ``` Then ask whether to investigate a resource or adjust thresholds.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.