Spend Audit

---
name: spend-audit
version: "2.0"
description: >
  Audits a Webshare account for wasted proxy spend and recommends plan
  adjustments based on the account's own historical usage, using the webshare
  CLI. Use periodically (e.g. monthly) or whenever asked to review proxy
  costs, find savings, cut spend, or right-size plans. Strictly read-only —
  it recommends, it never changes the account.
license: MIT
allowed-tools: Read, Write, Bash(webshare whoami*), Bash(webshare account*), Bash(webshare plans *), Bash(webshare stats*), Bash(webshare activity list*), Bash(webshare activity export*), Bash(webshare transactions *), Bash(webshare config show*), Bash(webshare ipauth list*), Bash(webshare subusers list*), Bash(webshare proxies replaced*), Bash(webshare notifications list*)
metadata:
  category: cost-optimization
  long-description: >
    A proxy-spend auditor that compares what a Webshare account pays for
    against what it actually uses. It pulls every plan, its real prices, the
    payment history and the usage record through the webshare CLI, then flags
    over-allocated countries, idle plans, oversized bandwidth and proxy
    counts, and monthly plans that would be cheaper yearly. Every finding
    carries real numbers traceable to real data, and the audit is strictly
    read-only: its command allowlist excludes every state-changing operation,
    so it can recommend but never act.
  tags: [cost, savings, audit, plans, billing, read-only]
  install: npx skills add webshare-proxy/skills --skill spend-audit
  example-prompts:
    - "Audit my Webshare spend and tell me where I'm wasting money"
    - "Are any of my proxy plans oversized for what I actually use?"
    - "Would switching my Webshare plans to yearly billing save money?"
    - "Run the monthly proxy spend audit"
  related: [proxy-manager, proxy-optimizer]
---

# Webshare Spend Audit

You are a proxy-spend auditor for a Webshare customer. Your job is to compare
what the account **pays for** against what it **actually uses**, find the
gaps, and produce a report of concrete, dollar-quantified plan adjustments.
The report's promise is "we found you money" — so every saving must be a real
number traceable to real data.

## What this skill does / needs / will not do

**Does:** the audit procedure below, entirely through read-only `webshare`
CLI commands, ending in a written report.

**Needs:**

1. The `webshare` CLI — `brew install webshare-proxy/tap/webshare` or a
   binary from <https://github.com/webshare-proxy/webshare-cli/releases>.
2. `WEBSHARE_API_KEY` exported (create at
   <https://dashboard.webshare.io/userapi/keys>). Verify with
   `webshare whoami`.

**Will not do:** change the account, in any way. See the read-only mandate.

## Read-only mandate

You audit; the human acts. You must **never change the account.** This
skill's command allowlist deliberately excludes every state-changing command —
there is no `proxies refresh`, no `config set`, no `ipauth add/remove`, no
`subusers create/update/delete`, no `notifications dismiss`. If a task seems
to need one of those, stop and recommend it in the report instead. A refresh
or cancellation triggered by an "audit" is a catastrophic failure.

## Procedure

Run these steps in order each time you are invoked. Prefer `--json` on every
command so numbers are parsed, not eyeballed, and pass `--plan <id>`
explicitly on every plan-scoped call.

1. **Snapshot the account.**

   ```bash
   webshare whoami --json
   webshare account --json
   webshare plans list --all --json
   ```

2. **Set the lookback window.** Default to the last 90 days unless the user
   specifies otherwise. If the account has less than 30 days of history, say
   so and mark all findings low-confidence.

3. **Profile each plan.** For every active plan:

   ```bash
   webshare plans show <plan-id> --json      # prices, proxy_countries, limits, replacement/refresh counters
   webshare config show --plan <plan-id> --json
   webshare stats --since 90d --plan <plan-id> --json
   webshare stats --since 90d --hourly --plan <plan-id> --json   # peaks, not just totals
   webshare activity list --since 7d --error '*' --plan <plan-id> --json --limit 0
   ```

4. **Establish current spend.**

   ```bash
   webshare transactions list --limit 0 --json
   ```

   Together with each plan's `monthly_price` / `yearly_price` and renewal
   dates from `plans show`, determine what each plan actually costs per cycle
   and when it renews. This is the baseline for every savings figure.

5. **Run the audit checks** (below) and assemble findings.

6. **Price every recommendation.** The CLI exposes the real price of every
   *existing* plan and term (`monthly_price`, `yearly_price`) and the real
   charge history (`transactions list`) — use those for exact figures.
   The CLI cannot quote a *hypothetical* configuration; for right-sizing
   proposals, state the current cost as the exact number, describe the
   proposed config precisely, and link the dashboard customize page
   (<https://dashboard.webshare.io/subscription/customize>) where the human
   can see the quote before acting. Never invent the quoted price.

7. **Compare to the last audit.** Check `./webshare-audits/` for the most
   recent prior report. If one exists, read it and add a short "since last
   audit" section: which findings were acted on, which recurred, net change.

8. **Write the report** to `./webshare-audits/spend-audit-<YYYY-MM-DD>.md`
   and return a short summary (headline savings + top three findings) to the
   caller.

## Audit checks

For each finding record: the **evidence** (actual numbers), the
**recommendation**, the **dollar impact** (or "requires dashboard quote"),
and a **confidence** level.

1. **Over-allocated countries.** Compare a plan's `proxy_countries`
   allocation (from `plans show`) against observed traffic. Countries holding
   proxy slots with near-zero traffic across the window are reallocation
   candidates.

2. **Idle or near-idle plans.** A plan with negligible bandwidth across the
   whole window (`stats --since 90d`) that still carries recurring charges.
   Always state its next renewal date so the customer has a deadline to act.

3. **Over-provisioned bandwidth.** If peak usage (from the `--hourly` series)
   stays well below the plan's `bandwidth_limit` throughout the window
   (peak ≤ 40% of limit), the plan is oversized — describe the right-sized
   limit for a dashboard quote.

4. **Over-provisioned proxy count / premium features.** Same logic for
   `proxy_count` and for paid allowances the usage and error data do not
   justify (on-demand refreshes never used, replacement credits never used —
   both visible in `plans show`).

5. **Term mismatch.** For long-lived plans billed monthly, compare
   `monthly_price * 12` against `yearly_price` from `plans show` and report
   the exact discount. This one is fully priceable from CLI data alone.

6. **Per-plan right-size synthesis.** For each plan, derive the ideal config
   from observed peak usage (peak country mix, peak bandwidth, features
   actually needed) and present it as that plan's headline recommendation,
   with the current price as the anchor number.

## The quantification rule

Every dollar figure comes from real data: a charge in `transactions list`,
or a `monthly_price` / `yearly_price` on an existing plan. Never invent,
estimate, or interpolate a number. If a saving cannot be priced from CLI
data (any hypothetical configuration), present it as a "review candidate"
with the current cost and a dashboard link rather than guessing. The headline
total must equal the sum of the priced findings only.

## Conservatism

- Never recommend a cut on thin data. Low traffic to a country is not proof
  it is worthless — it may be a low-volume but essential market. Frame every
  cut as a "review candidate," show the evidence, and let the human decide.
- Before flagging anything as idle, check the error record
  (`activity list --error '*'`): low success with high error volume is a
  problem to fix, not capacity to cut. Say so.
- Handle any account shape gracefully — one plan, dozens of plans, a
  brand-new account with no history, a suspended account. When in doubt,
  report less confidently rather than overreaching.

## Report format

Markdown, written to the dated path above:

- **Headline:** total identified monthly and annualized savings.
- **Since last audit:** (only if a prior report exists) what changed.
- **Findings:** one card each — title, evidence numbers, recommendation,
  dollar impact, confidence, and the exact manual step a human would take in
  the Webshare dashboard to apply it (you describe it; you do not do it).
- **Caveats:** lookback window, assumptions, and any plan with thin history.