---
name: handle-budget-limited-campaigns
description: >-
  Diagnoses and resolves a campaign pinned against its daily budget. First decides whether the cap
  is even a problem worth money: a profitable capped campaign with flexible budget just gets a
  raise; an unprofitable one gets efficiency fixes, never more spend. When budget genuinely cannot
  rise, it works an ordered sequence inside the cap, concentrate on the best converters, cut
  search-term waste, pull budget from losing campaigns, tighten the target 5-10% so the algorithm
  gets pickier, and protect the top performer, then validates over two weeks. Use it when
  IS lost to budget exceeds ~10% on a profitable campaign or the budget exhausts before peak hours.
  Not for account-wide allocation (allocate-budget-across-campaigns), deliberate growth pushes
  (scale-bids-and-budgets), or general strategy sickness (monitor-and-maintain-bid-strategy-health).
---
# Resolve Budget-Limited Campaigns

## Purpose
"Limited by budget" is either the best problem in the account (a proven campaign that wants to
spend more) or a trap (a loser that would only lose faster with more money). This skill separates
the two cases with data, then either raises the budget cleanly or squeezes more results out of a
fixed cap through waste removal, reallocation, and target discipline.

## When to run
- IS lost to budget > ~10% on a campaign meeting its CPA/ROAS target.
- The campaign spends its full daily budget before high-converting hours.
- A weekly review shows chronic "limited by budget" status.
- A fixed client/monthly cap forces optimizing within the current spend.

## When NOT to run
- Rebalancing the whole account's budgets -> allocate-budget-across-campaigns.
- The campaign is healthy and uncapped and you want growth -> scale-bids-and-budgets.
- The strategy is in learning, misconfigured, or volume-starved ->
  monitor-and-maintain-bid-strategy-health.
- The waste problem is broad query-level noise across campaigns -> analyze-search-term-reports or
  run-n-gram-analysis directly, then return here.

## Prerequisites
- 30 days of campaign performance (cost, conversions, CPA/ROAS).
- Breakeven CPA/ROAS from calculate-bid-targets (profitability cannot be judged without it).
- Whether the budget is flexible or hard-capped (ask the user; this forks the whole procedure).

## Procedure
1. **Session guardrail.** Call `gads_policy_guardrail` before the session's first write.
2. **Baseline pull.** Via `gads_run_gaql_query`: daily budget, spend, conversions, actual
   CPA/ROAS vs target, `metrics.search_budget_lost_impression_share`, and
   `metrics.search_rank_lost_impression_share` for the last 30 days. Record it, step 10 compares
   against this.
3. **Classify the constraint.** High IS lost to budget with low IS lost to rank -> a pure budget
   cap (this skill's case). Both high -> if profitable, raise budget first and treat rank later;
   if unprofitable, competitiveness/quality is the real issue, fix efficiency before any budget
   talk. Low IS lost to budget despite the "limited" flag -> intermittent peaks only; a small raise
   or nothing.
4. **Profitability gate.** Compare actual CPA/ROAS to breakeven and target. Unprofitable ->
   do NOT raise budget under any circumstance; route to efficiency work (search-term waste below,
   plus improve-quality-score / landing-page work) and stop here. Profitable + flexible budget ->
   step 5. Profitable + hard cap -> steps 6-9.
5. **The easy win (write).** Raise the budget with `gads_update_budget`, a profitable campaign
   leaving 10%+ of impressions unbought deserves money without ceremony. Preview
   (validate_only=true default) showing old/new amount and expected volume recapture; apply after
   user approval. Keep single raises <=30% to avoid a learning reset; repeat after 1-2 weeks if IS
   lost to budget stays high. Then jump to step 10.
6. **Constrained path, cut waste first.** Pull `gads_get_search_terms_report` for 30-60 days.
   Identify spend with zero or breakeven-negative conversions. Apply exclusions via
   `gads_add_negatives_from_search_terms`, preview the full negative list, apply only after user
   approval. This is recovered budget with no volume cost.
7. **Reallocate from losers (write).** Query sibling campaigns via `gads_run_gaql_query`, sorted
   by CPA (or ascending ROAS). Campaigns beyond breakeven for 30+ days give up 20-30% of their
   budget; the capped performer receives it. Both sides go through `gads_update_budget`
   preview -> approval. Never take budget from another campaign that is meeting target, funding
   one winner by starving another is churn, not optimization.
8. **Tighten the target (write).** If steps 6-7 freed too little: make the algorithm choosier with
   `gads_set_campaign_bidding_strategy`, reduce target CPA 5-10%, or raise target ROAS 5-10%.
   Wait 1-2 conversion cycles per adjustment. The target, not the budget cap, is the reliable
   efficiency throttle: a tight budget with a loose target does not preserve good actuals. If you
   inherit that inverted setup (low budget throttling a loose target), flip it, set the target
   you actually want and give the budget room.
9. **Narrow if tiny (write).** For very low budgets where the above is insufficient: pause
   low-intent, non-converting keywords via `gads_pause_keyword` (previewed list, user approval),
   and consider concentrating on the best ad groups and geographies. After 30 days, judge with
   proxy signals if conversions are too thin, converting exact-match terms mean cautiously
   re-broaden; decent engagement but no conversions means check tracking or sales-cycle length;
   nothing at all means restructure rather than persist.
10. **Validate (2 weeks).** Re-pull step 2's metrics. IS lost to budget < 10% with efficiency
    held -> done, document the new baseline. Improved on both axes -> consider
    scale-bids-and-budgets. Volume collapsed -> over-tightened; relax step 8-9 changes.
    Unchanged -> the constrained toolbox is exhausted; a budget increase is now evidence-backed.
11. **HUMAN STEP (outside VigilDog).** If step 10 lands on "increase justified" under a hard cap,
    present the stakeholder the case: current IS lost to budget, efficiency vs target, and the
    modeled volume recapture per extra unit of budget.

## Decision rules
- **Trigger:** IS lost to budget >10% on a profitable campaign; >20% is priority-urgent.
  0-10% is normal pressure, no action.
- **Cardinal rule:** unprofitable + capped never gets more budget; more spend just accelerates the
  loss.
- **Raise sizing:** <=30% per change, 1-2 weeks apart (bigger jumps risk a learning reset).
- **Target tightening:** 5-10% per move, never >20% at once; 1-2 conversion cycles between moves.
- **Reallocation source test:** only campaigns past breakeven for 30+ consecutive days; reduce
  them 20-30%, not to zero.
- **Priority among multiple capped campaigns:** best efficiency first; if the capped campaign is
  the account's #1 performer, it outranks every other budget claim immediately.
- **Order matters:** waste removal (free) before reallocation (cheap) before target tightening
  (costs volume) before narrowing (costs reach) before asking for money (costs credibility if the
  first four were skipped).

## Common failure modes
- **Feeding a loser.** Skipping the profitability gate and raising budget because "limited by
  budget sounds bad", the flag describes pacing, not health.
- **Mass keyword pausing.** Over-aggressive narrowing collapses volume beyond what the budget cap
  ever cost; pause in small batches with a week between rounds.
- **Big target jerks.** A >20% target change restarts learning and destabilizes exactly the
  campaign you were trying to squeeze; stay at 5-10%.
- **Robbing the winners.** Reallocating from a target-hitting campaign creates a second capped
  winner; sources must be genuinely below breakeven.
- **No validation window.** Declaring victory without the two-week re-check leaves silent volume
  loss undiscovered until the monthly report.

## Related skills
- Before: calculate-bid-targets (breakeven), allocate-budget-across-campaigns (if the whole
  account's split is the real issue).
- During: analyze-search-term-reports, run-n-gram-analysis (deeper waste passes).
- After: scale-bids-and-budgets (once uncapped and healthy),
  monitor-and-maintain-bid-strategy-health (recurring watch so the cap does not silently return).