budget-auditor
Audit budget limitation, sufficiency, monthly pacing, allocation, and shared-budget health across 19 diagnostics in 5 modules. Scores 0-100 per module, never mutates the account. AUTO-ACTIVATE for: "b
SKILL.mdclients/lefup/.claude/skills/budget-auditor/SKILL.md
GitHubBudget Auditor
Diagnose-only skill that scores account-wide budget health across 19 diagnostics organized into 5 modules. Read-only — never modifies the account.
Scores 0-100 weighted across:
- Allocation (30 pts)
- Limitation (25 pts)
- Pacing (15 pts)
- Sufficiency (15 pts)
- Shared Budgets (15 pts)
Diagnostic ≠ recommendation. Phase 1.5 walks the constraint cascade Measurement → Business → Bidding → Efficiency → Conversion → Competitive → Structural → Traffic before any action is written. Raising budget is the most-gated action in the entire skill set; the auditor must form a root-cause hypothesis first — see reference/synthesis-playbook.md.
Handoff: Findings route through reference/handoff-matrix.md. Two layers are blocking — Measurement (/tracking-specialist) and Business (/strategy-specialist). The optimizer hard-refuses any raise while a blocking layer is active.
Peer with bidding-specialist. Budget and bid moves are co-equal levers; this skill owns the budget side only. Target CPA/ROAS adjustments stay with /bidding-specialist.
Command Routing
/budget-auditor → Full audit (all 5 modules) + opportunities
/budget-auditor limitation → Module 1 only (BUD-D01–D04)
/budget-auditor sufficiency → Module 2 only (BUD-D05–D08)
/budget-auditor pacing → Module 3 only (BUD-D09–D12, lighter pull)
/budget-auditor allocation → Module 4 only (BUD-D13–D16)
/budget-auditor shared → Module 5 only (BUD-D17–D19)
/budget-auditor opportunities → Cross-cutting opportunity-only report
/budget-auditor reconfirm → Re-run Phase 0 interview
/budget-auditor {30|60|90} → Custom audit window
/budget-auditor {module} {period} → Module + period combination
/budget-auditor base-only → Exclude active experiment variants (rare; structural audits only)
Default evaluation period: 30 days. Options: 30, 60, 90.
Scope filters (always-on): Removed and paused campaigns are excluded at the GAQL layer (campaign.status = 'ENABLED' and campaign.serving_status = 'SERVING'). No data is pulled for them.
Experiment campaigns: INCLUDED by default because active experiment variants consume real daily budget — excluding them would under-count spend and break Allocation, Pacing, IS Lost (Budget), and exhaustion-timing math. This inverts bidding-auditor's default.
Pass base-only (or set budgetAudit.includeExperiments: false) to drop experiment-type rows. Removed/paused campaigns are always excluded regardless. The base-only token composes with any other arg (e.g. /budget-auditor allocation 60 base-only).
Phase 0: Prerequisites & Data Collection
Phase 0.0: Business Context Resolution
Read: config/ads-context.config.json → budgetAudit and top-level accountCurrency. See reference/configuration.md for the schema.
Branch A — Cached values fresh (lastConfirmed exists, businessMdHash matches the current business.md hash, < 60 days old):
"Using cached budget context: monthly target ${monthlyBudgetTotal} ${accountCurrency}, ${N} per-campaign overrides, seasonality ${seasonalityProfile.mode}. Last confirmed ${lastConfirmed}. Proceed? (y / update)"
If "y" → continue to Phase 0.1. Otherwise → Branch B.
Branch B — First run, stale, or reconfirm requested:
Read
context/business.md. Form drafts:monthlyBudgetTotalif mentioned- currency hint (
USD,EUR, etc.) for the top-levelaccountCurrency - any seasonality language ("Black Friday", "Q4 push", "summer slowdown")
Read currently-enabled campaigns from
context/google-ads/data/. Compute current monthly run-rate for the read-back baseline.Show baseline:
"I see ${N} enabled campaigns currently running ~${currentMonthly} ${currency}/month. Account-level monthly target?"
Offer business.md write-back: if the user provides a number not currently in business.md, ask:
"Want me to add this monthly target to business.md so it's the source of truth?"
Optional per-campaign targets:
"Want to set per-campaign targets for the campaigns you actively manage budgets for? (y / skip — defaults to even allocation across the total)"
When yes, ask for
{ "campaign name": { "monthly": N, "priority": "protect"|"scale"|"hold" } }for each one.Seasonality interview:
"Does your business have seasonality? (y / n)"
If yes:
"Which months matter? (e.g., May, November, December)"
Stored as
seasonalityProfile.mode = "highlight_months"with a lowercased month list.Confirm thresholds. Present the static defaults inline; only override when the user explicitly does. Include
dailyBudgetToCpaRatio,overspendAlertPp,underspendAlertPp,isLostBudgetThreshold,maxSingleMutationMultiplier.Currency: If top-level
accountCurrencyis missing, ask:"Account currency? (default USD)"
Write to top-level config.
Fallback escape hatch: If the user can't supply
monthlyBudgetTotal:"No monthly target available — should I run in fallback mode? (Pacing module will be skipped; allocation/limitation/sufficiency/shared still run.) (y / n)"
On yes, set
targetFallbackMode = "no_monthly_target".Write
budgetAuditblock +businessMdHash = sha256(business.md).slice(0,16)+lastConfirmed = today. Static defaults stay untouched unless the user overrode any.
Phase 0.1: Config Validation
Verify required fields:
- top-level
accountCurrency(default to "USD" with a one-line warning if missing) - either
budgetAudit.monthlyBudgetTotalis set ORbudgetAudit.targetFallbackMode === "no_monthly_target"
If validation fails → re-run Phase 0.0 Branch B.
Phase 0.2: Data Freshness
Two checks:
gads-context — same pattern as keyword-auditor and bidding-auditor. If stale (>24h), prompt to refresh via
/gads-context.context/account-changelog.md— read mtime + the date in the file's header.- If file missing OR >24h old, prompt:
"Account changelog is {N}d old. Refresh first via /account-changelog? (y / skip)"
- On the FIRST stale prompt of the session, also offer:
If yes, set"Want me to auto-refresh account-changelog whenever it's stale during this session? (y / no, ask each time)"
budgetAudit.accountChangelogConsentForSession = today(in-memory; not persisted across sessions). - On skip → banner the report: "Change history may be stale — recent budget edits not reflected in diagnostics."
- If file missing OR >24h old, prompt:
The optimizer enforces a stricter 1-hour freshness on the changelog and auto-refreshes; the auditor's threshold is 24h.
Phase 0.2.5: Experiment Scope
Default: all currently SERVING campaigns — base AND active experiment variants. Inverse of bidding-auditor. Active experiments share/split the daily budget with their base, so excluding them would break spend, IS, and pacing math.
Filter resolution:
- CLI flag
base-only(or--include-experiments=false) → exclude experiment variants. budgetAudit.includeExperiments === false→ exclude experiment variants.- Otherwise → include.
When EXPERIMENT-type campaigns are pulled, banner the report:
"ℹ️ Audit includes ${N} active experiment campaign(s). Spend, IS, and pacing reflect base + experiment serving share."
Module 4 (Allocation) groups experiment rows under their base so a base+experiment pair counts as ONE budget consumer. Module 5 (Shared Budgets) flags experiment-variant in shared pool as a configuration risk inside BUD-D17.
Phase 0.3: Module-Scope Determination
Parse the subcommand → choose which queries to pull:
| Subcommand | Queries pulled |
|---|---|
| (full) | all 5 |
| limitation | campaign-budgets + campaigns-budget-perf |
| sufficiency | campaign-budgets + campaigns-budget-perf + campaigns-pacing-daily + bidding-strategies |
| pacing | campaign-budgets + campaigns-pacing-daily + campaigns-budget-perf + account-budget |
| allocation | campaign-budgets + campaigns-budget-perf |
| shared | campaign-budgets + campaigns-budget-perf + bidding-strategies |
| opportunities | campaign-budgets + campaigns-budget-perf + campaigns-pacing-daily |
Phase 0.4: Data Pull
Run scoped batch pull (default INCLUDES experiments):
node .claude/skills/budget-auditor/scripts/pull-all.js \
--period={evaluationPeriod} --lag={conversionLagDays} --module={moduleScope} \
[--base-only]
The script writes CSVs to context/google-ads/data/. It prints __RESULTS_JSON__ on the last line — parse to confirm row counts and the resolved experiment scope.
Tell the user: "Pulled {N} campaigns, {M} budgets, {S} portfolios. Experiments: {INCLUDED|excluded}. Running analysis…"
Phase 1: Run Diagnostics
Read each module's diagnostic-rules file:
reference/diagnostic-rules-limitation.md(Module 1)reference/diagnostic-rules-sufficiency.md(Module 2)reference/diagnostic-rules-pacing.md(Module 3)reference/diagnostic-rules-allocation.md(Module 4)reference/diagnostic-rules-shared.md(Module 5)
Dispatch to engines based on module scope:
# Modules 1, 2, 4, 5 — produces findings-health.json + opportunities-health.json
node .claude/skills/budget-auditor/scripts/analyze-budget-health.js \
--period={evaluationPeriod}
# Module 3 — produces findings-pacing.json + opportunities-pacing.json + pacing-projection.csv
node .claude/skills/budget-auditor/scripts/analyze-pacing.js
Each engine writes to context/analysis/budget/.
Read the findings JSONs, then assign verdicts per reference/scoring-model.md:
| Verdict | Effect |
|---|---|
| PASS | full points retained |
| WARN | 40% deduction |
| FAIL | 100% deduction |
| INFO | informational, no points at stake |
| SKIP | excluded; denominator reduced |
Phase 1.5: Synthesis & Constraint Cascade (MANDATORY)
Read reference/synthesis-playbook.md in full before writing any recommendation. The whole point of the cascade is that "raise the budget" is almost always the wrong first move when an upstream layer is dirty.
Output: a ranked hypothesis list, each with:
- layer (M / B / Bid / Eff / Conv / Comp / Struct / T)
- evidence (which diagnostics)
- confidence (low / medium / high)
- whether it blocks downstream raise actions
Required checks (every audit):
- M layer — tracking-specialist findings on flagged campaigns? Active → blocks all raise mutations.
- B layer — break-even or primary KPI missing? Active → blocks profitability-dependent diagnostics (BUD-D03/D04/D13/D14/D15) and any raise.
- Bid layer — BUD-D05, BUD-D08, BUD-D19 fire? Sequence
/bidding-specialistbefore any budget mutation on the affected campaigns. - Eff layer — fresh search-term/keyword/QS audits show waste on flagged campaigns? Recover efficiency before raise.
- Conv layer — CVR is the bottleneck on a budget-limited profitable campaign?
/lp-auditor,/offer-auditorfirst. - Comp layer — IS Lost (Rank) > IS Lost (Budget) on flagged campaign? Decompose via
/competitive-analyst. - Struct layer — zero-spend or daypart exhaustion?
/account-auditor,/geo-schedule-auditor,/account-changelog. - T layer — pure budget action (raise/reduce/reallocate/share-fix) — only after the cascade clears.
Anti-patterns
- Never recommend a raise while M or B is blocking. Replace with the handoff.
- Never recommend a raise on a campaign with
state = unprofitable— that's a reduce candidate. - Never recommend stacking a raise + reduce on the same campaign in one session.
- Never propose a single-mutation jump >
maxSingleMutationMultiplier(default 1.3×) without explicit--aggressive. - Never write a flat actions table that mixes a tracking handoff with a raise — segment by cascade state per the report template.
Phase 2: Score & Report
Read reference/scoring-model.md. Compute:
- module sub-scores (after deductions)
- N/A redistribution if any module SKIPs entirely (no shared budgets, fallback-mode pacing, all-PMax-no-tCPA Sufficiency split)
- weighted total
Bands
| Score | Grade |
|---|---|
| 90–100 | Excellent |
| 75–89 | Good |
| 60–74 | Needs Attention |
| <60 | Critical |
Write report to context/analysis/budget-audit.md
Read reference/report-template.md. Section order:
- Executive read (prose, 2–4 paragraphs)
- Score, grade, window, run timestamp, banners (experiments, fallback mode, stale changelog)
- Top hypothesis row
- Module score table (5 rows)
- Risks segmented: 🔍 Investigate first / 🔧 Bidding-side fix / 🔄 Recover efficiency / ⚖️ Allocation / ✅ Act now / ⚠️ Hold
- Opportunities (always present)
- Pacing snapshot (if module ran)
- Sequenced handoffs
- Per-diagnostic appendix
Append to context/analysis/budget-audit-log.md:
## {date} — Score: {score}/100 ({grade})
- Period: {period}d | Campaigns: {n} | Consumers: {m}
- Top hypothesis: {layer} — {label}
- Active blocking: {comma list or "none"}
- Top finding: {1-line}
Phase 3: Opportunities Pass (unconditional)
Always run, even when zero risk findings. Cross-cutting opportunities surfaced by the engines:
- profitable_limited_recovery — IS-lost-budget recovery on a profitable campaign. Includes projected incremental conversions, cost, and CPA/ROAS at the projected unit cost.
- winner_underfunded — profitable campaign capturing < 15% spend share with material IS Lost (Budget).
- seasonality_ramp — next month is a designated highlight month and budgets haven't been raised.
- underspend_redeploy — pacing projects underspend; surface unspent dollars for reallocation.
Each entry: type, scope, $-projection, recommended optimizer subcommand. Currency rounding is to the nearest dollar (transparency over tidy numbers).
Phase 3.5: Peer Report Lookup (MANDATORY before handoff)
Don't send the user from one door to the other. Before recommending any peer-skill handoff in Phase 4, check whether that peer has already produced a fresh report — and if so, read it and integrate its findings into THIS report instead of asking the user to re-run.
The whole point of cross-skill awareness is that a user who runs /quality-score-auditor last week and then runs /budget-auditor this week sees the QS findings quoted inside the budget report, not a redundant "go run QS" instruction. Re-running an auditor that already produced a fresh answer wastes the user's time and obscures the budget-side action.
Freshness windows
| Peer skill | Report file | Fresh window |
|---|---|---|
/quality-score-auditor |
context/analysis/quality-score-audit.md |
≤ 7 days |
/search-term-auditor |
context/analysis/search-term-audit.md |
≤ 7 days |
/keyword-auditor |
context/analysis/keyword-audit.md |
≤ 7 days |
/competitive-analyst |
context/analysis/competitive-audit.md |
≤ 14 days |
/lp-auditor |
context/analysis/lp-audit.md |
≤ 14 days |
/offer-auditor |
context/analysis/offer-audit.md |
≤ 30 days |
/bidding-auditor |
context/analysis/bidding-audit.md |
≤ 7 days |
/tracking-specialist |
context/analysis/tracking-audit.md |
≤ 30 days |
/strategy-specialist |
context/analysis/strategy-audit.md |
≤ 30 days |
/account-auditor |
context/analysis/account-audit.md |
≤ 30 days |
Procedure for each peer that the cascade would otherwise hand off to
- Check if the file exists. If not → keep the handoff as a plain "run
/peer-skill" line. - If it exists, check mtime AND the date in the report header against the freshness window.
- If fresh: open the report and read its executive read / top hypothesis / module scores / risks. Pull out the 1–3 findings that overlap with this audit's flagged campaigns or hypotheses. Use them to:
- Enrich the Executive read at the top of
budget-audit.md— quote the peer's score, the headline finding, and the date inline. - Replace the Phase 4 line "run
/peer-skill" with: "Review the existing {date} {peer} report at {path} — top finding: '{one-liner}'. Re-run only if you want fresher data." - In the Risks section, when an Eff/Conv handoff is the top hypothesis, quote the peer's specific finding (campaign names, page URLs, search-term n-grams, etc.) so the user can act without leaving the budget report.
- Enrich the Executive read at the top of
- If stale: mention "a previous {peer} report exists from {date} but is {N} days old — recommend re-running before relying on it" and keep the handoff as a re-run.
- If missing: standard "run
/peer-skill" handoff.
When a fresh peer report contradicts a budget hypothesis
Say so explicitly in the Executive read. Example: budget-auditor flags BUD-D03 (profitable + IS Lost (Budget) 22% on Branded Search) and would normally route to /budget-optimizer raise — but the fresh QS report shows the same campaign has rank-lost IS at 90% driven by LP issues. Loosening the budget won't recover that lost traffic; LP fixes will. The budget report must say this, not silently propose the raise.
That cross-skill validation is the entire reason this phase exists. A budget audit that ignores a fresh QS or LP audit is worse than no budget audit, because it produces a confidently-wrong recommendation.
Phase 4: Sequenced Handoff Offer
Apply Phase 3.5 lookup results, then render per reference/handoff-matrix.md. Always sequence by cascade priority — never present as a flat menu.
When upstream is dirty:
Top hypothesis: {layer} — {label}
Before any budget change, run in order:
- {M handoff if active} →
/{skill}- {B handoff if active} →
/{skill}- {Bid peer (if Bid layer firing)} →
/bidding-specialist- {Eff layer} →
/search-term-auditor,/quality-score-auditor, etc.- {Conv layer} →
/lp-auditor,/offer-auditor- {Comp / Struct (informational)} →
/competitive-analyst,/account-auditor- {T —
/budget-optimizeronly after the above clear}
- {N} reallocations →
/budget-optimizer reallocate- {M} reductions →
/budget-optimizer reduce- {K} raises (gated) →
/budget-optimizer raise
When all clear:
Cascade clears 1–7 are green. Ordered by priority:
- Always-safe:
/budget-optimizer fix-shared,/budget-optimizer pacing-adjust- Reallocate:
/budget-optimizer reallocate- Reduce:
/budget-optimizer reduce- Raise (gated):
/budget-optimizer raise
Only show subcommands with findings to act on.
Phase 5: Report Generation
Already written in Phase 2; Phase 5 is the user-facing presentation. The reader should be able to act on the Executive read alone — that's the bar. Everything else is reference material for when they want detail.
Lead with the Executive read (prose, ~300 words, no bullet lists). It must:
- State what the score actually means in plain language (not just the band).
- Name the 1–3 things that matter this week, ranked, each with the why.
- Name what is NOT a problem so red text below doesn't waste attention.
- Quote inline any fresh peer-report findings discovered in Phase 3.5 (date, score, one-line top finding) — this is the most valuable line in the report.
- End with one line on how to read the rest.
Then in this order:
- Diagnosis paragraph (technical restatement of the cascade hypothesis).
- Top hypothesis row.
- Module score table (5 rows; mark N/A modules clearly).
- Risks segmented by cascade state (🔍 Investigate first / 🔧 Bidding-side fix / 🔄 Recover efficiency / ⚖️ Allocation / ✅ Act now / ⚠️ Hold / ℹ️ Confirm intent). Each line that hands off to a peer skill integrates the fresh peer's specific finding when one exists — never a bare "go run X".
- Opportunities table (always present, even on healthy accounts).
- Pacing snapshot (when Module 3 ran).
- Sequenced handoffs (numbered protocol — see Phase 4 template).
- Module details appendix.
- Configuration snapshot.
- One-line: "Full report saved to
context/analysis/budget-audit.md."
Read reference/report-template.md for the full template + style guidelines (prose first, quote-don't-link, sequence-don't-menu, name-reality-not-just-verdict).
The Executive read is the contract: a user who only reads the first paragraph should still leave with the right next action.
Edge Cases
| Scenario | Handling |
|---|---|
| No shared budgets in account | Module 5 SKIP entirely; 15 pts redistribute. |
targetFallbackMode = "no_monthly_target" |
Module 3 SKIP; 15 pts redistribute. Banner the report. |
monthlyBudgetTotal = null AND no fallback |
Phase 0.1 fails; re-run interview. |
primaryKPI / break-even missing |
BUD-D03/D04/D13/D14/D15 return INFO with blocking: ['business']; route to /strategy-specialist. Other diagnostics still run. |
| Single-campaign account | Allocation diagnostics SKIP; report notes the structural gap. |
| account-changelog missing or >24h | Prompt the user; cache consent for the session if they say "auto-refresh from now on". |
| Account-budget query fails (non-invoicing) | Soft-fail, don't error the whole run. Logged as SKIP. |
| New campaigns (<14d old) | Marked INFO with "new — monitoring" note inside findings; no raise recommendation. |
| All-PMax account with no tCPA | BUD-D05 SKIPs (single-diagnostic); module remains scored on BUD-D08. |
| Currency other than USD | All money columns formatted via top-level accountCurrency. |
| API rate limit | pull-all.js delegates to query.js which retries; surfaces error and exits 1. |
| Conversion lag > evaluation window | Re-run with longer window — surface as M2 hypothesis. |
| Recently raised budget (<14d) | Findings annotate "in learning"; optimizer hard-refuses any raise on the same campaign for 14d. |
Known Gaps (v1)
- BUD-E08 monitoring alerts — deferred to v1.1; will write
monitoring/budget-alerts.jsonfor the future/daily-monitororchestrator. - Performance Planner integration — opportunity projection uses the
is_lost_budgetheuristic; v1.1 swaps in CampaignBidSimulatorService and Performance Planner forecasts. - Hourly segmentation for BUD-D06 — daily 95% threshold is the v1 stand-in; v1.1 adds hourly when row-count tradeoff is acceptable.
- Per-channel scoring weights — single set of module weights for v1; v1.1 will diverge if Search/PMax/Shopping accounts diverge enough in practice.
bid-budget-reviewerorchestrator — v1.1; for now the report sequences bidding-specialist + budget-optimizer handoffs explicitly.