Underspending Investigation

Underspending Investigation

Purpose: Investigate why a Google Ads account is underspending and determine the root cause with actionable, data-backed recommendations.

Type: Read-only investigation skill. Reads campaign/IS data and pacing sheets; never writes to Google Ads.

---

Inputs

The skill expects:

• {ACCOUNT_NAME} — full account name (e.g., Example Property - Pmax)
• {ADDITIONAL_CONTEXT} (optional) — pacing variance or other prior context (e.g., Underspending by +12.5%)

When invoked via Task(subagent_type="general-purpose", prompt="Use the underspending-investigation skill to investigate …"), the orchestrator substitutes both values into the prompt.

---

Auto-Load Domain Knowledge Skills

CRITICAL: At the start of every investigation, auto-invoke these companion skills via the Skill tool to load the frameworks, formulas, and decision trees:

1. campaign-line-filtering — Which campaigns to analyze based on account designation (Pmax / Demand Gen / Search by name suffix)
2. portfolio-pacing-rules — Pacing thresholds and budget management philosophy for your portfolios
3. google-sheets-lookups — Reference for budget and pacing data sources
4. google-ads-query-patterns — GAQL patterns for data extraction
5. impression-share-diagnostics — Root-cause diagnosis framework for Search campaigns
6. budget-recommendation-calculator — Conservative budget calculation methodology

Do this BEFORE analyzing script output. These six companion skills are each shipped as standalone skills in this repo.

---

Investigation Protocol

STEP 0: Run the Universal Investigation Script

python investigate_underspend.py "{ACCOUNT_NAME}"

The script (which you adapt to your own data sources — see "Script Contract" below) should:

1. Resolve the customer ID for the account
2. Run a 7-day campaign spend analysis (budget utilization, performance)
3. Pull impression share metrics (Search IS, Budget Lost IS, Rank Lost IS) for Search campaigns
4. Pull MTD pacing data from your pacing dashboard
5. Optionally pull recent optimization log entries

The script handles data collection. The skill's job is to read/interpret the script output, apply the diagnostic frameworks from the auto-loaded companion skills, and synthesize findings into actionable recommendations.

---

Step 1: Recent Optimizations Check

Reference Skill: google-sheets-lookups

Goal: Determine if recent budget changes explain the underspending.

Decision Point (from portfolio-pacing-rules):

• IF recent budget increase found (last 3-7 days):
• Diagnosis: "Normal ramp-up period after budget increase"
• Recommendation: "Monitor over next 3-5 days, no action needed"
• STOP investigation here ✅
• IF budget increase 7-14 days ago:
• Note in findings; CONTINUE to Step 2 (should be ramped up by now)
• IF no recent budget changes:
• CONTINUE to Step 2

---

Step 2: Campaign Spend Pattern Analysis

Reference Skill: campaign-line-filtering

Goal: Understand which campaigns are spending and how budgets are structured.

Key Analysis:

• Budget structure: Shared vs. individual budgets
• Budget utilization %: MTD spend ÷ MTD budget allocation
• Campaign status: ENABLED, PAUSED (with MTD spend), vs. ENDED (excluded)
• Bidding strategy: Smart bidding type (Max Conversions, Max Conversion Value, etc.)

Standard filters applied by the script:

• Filter campaigns by line designation (Pmax / Demand Gen / Search by account name suffix)
• Exclude campaigns with $0 MTD spend
• Exclude ENDED / REMOVED campaigns
• Compute 7-day and MTD spend averages

Skill analysis:

• Review filtered campaign list
• Note unusual patterns (paused campaigns with spend, shared-budget imbalances)
• Identify primary spending campaigns

---

Step 3: Impression Share Analysis (Root Cause Diagnosis)

Reference Skill: impression-share-diagnostics

Goal: Diagnose WHY underspending is happening using impression share metrics.

Diagnostic Framework (from impression-share-diagnostics):

| Search IS | Budget Lost IS | Rank Lost IS | Diagnosis | Next Step | |-----------|----------------|--------------|-----------|-----------| | 30% | >50% | Budget too low | Step 4: Calculate budget recommendation | | 60% | Quality issues | Recommend quality improvements | | >80% | 80% of target)

• If performance is failing, do NOT recommend budget increase

Performance Max caveat: Pmax campaigns do NOT expose meaningful Search IS / Budget Lost IS / Rank Lost IS. For Pmax, use alternative diagnostics: budget utilization %, performance vs. goal, asset performance scores, auction insights (when available).

---

Step 4: Budget Recommendation (If Applicable)

Reference Skill: budget-recommendation-calculator

Goal: Calculate a specific, conservative budget recommendation.

When to recommend a budget increase:

• ✅ Pacing variance exceeds your portfolio's tolerance
• ✅ Budget Lost IS >10% (spend potential exists) — or for Pmax, low budget utilization with strong performance
• ✅ CPA / ROAS performance acceptable
• ✅ No recent budget increase in last 7 days
• ✅ At least 5 days into the month

Calculation Method (from budget-recommendation-calculator):

Target Monthly Budget = Current Monthly Budget × (1 + (Pacing Variance × Adjustment Factor))

Where:
- Pacing Variance = from script output
- Adjustment Factor = 0.5 (standard conservative — only close half the gap)

HARD CAP: Never exceed 10% increase in a single change

Example:

Current Monthly Budget: $1,000
Pacing Variance:        +13.18%
Adjustment Factor:      0.5

Target = $1,000 × (1 + (0.1318 × 0.5))
       = $1,000 × 1.0659
       = $1,065.90

Recommended: $1,065 (6.5% increase)
Daily Budget: $1,065 ÷ 31 days = $34.35/day

When NOT to recommend a budget increase:

• ❌ CPA significantly above goal (>20% over)
• ❌ Recent budget increase within last 7 days
• ❌ Search IS >80% + Budget Lost IS ` as fallback)
• Resolve customer ID for the account
• Output a 7-day campaign spend section (per-campaign budget, utilization %, status, bidding strategy, performance metrics)
• Output an impression share section for Search / Pmax campaigns (Search IS, Budget Lost IS, Rank Lost IS)
• Output a month-to-date pacing section (monthly budget, MTD spend, variance %, days elapsed)
• Optionally output recent optimization log entries

Reference implementation hooks:

• Google Ads API access via google-ads-python (loads credentials from google-ads.yaml)
• Pacing dashboard read via Google Sheets API (configure your sheet ID via env var, e.g. PACING_SHEET_ID)
• Account registry for CID lookups (your accounts.json or equivalent)

---

Output Format

Return findings in this exact structure:

================================================================================
UNDERSPENDING INVESTIGATION: {ACCOUNT_NAME}
================================================================================

INVESTIGATION SUMMARY:
- Account: {Full account name}
- Customer ID: {CID}
- Date: {Current date}
- Investigation time: {How long it took}

================================================================================
ROOT CAUSE DIAGNOSIS
================================================================================

Primary Issue: {Budget Constraint | Quality Issues | Low Demand | Ramp-Up Period | Other}

Evidence:
- Pacing Variance: +X.X% (from pacing dashboard)
- Search Impression Share: XX%
- Budget Lost IS: XX%
- Rank Lost IS: XX%
- CPA: $XX.XX (Goal: $XX.XX) {✅ or ❌}

Explanation:
{2-3 sentence explanation of WHY underspending is happening}
{Reference the diagnostic framework from impression-share-diagnostics}

================================================================================
DETAILED FINDINGS
================================================================================

Step 1: Recent Optimizations
{Summary from script output — any recent budget changes?}

Step 2: Campaign Spend Analysis
{Filtered campaigns, budget structure, utilization %}
{Note: Script already filtered by line designation per campaign-line-filtering}

Step 3: Impression Share Analysis
{IS metrics per campaign, interpreted using impression-share-diagnostics decision tree}

{Any additional investigation steps taken}

================================================================================
RECOMMENDATIONS
================================================================================

{Use budget-recommendation-calculator framework}

BUDGET RECOMMENDATION:
{If recommending increase:}
✅ Increase Monthly Budget: $X,XXX → $X,XXX (+X.X%)
✅ New Daily Budget: $XX.XX/day

Rationale:
- Pacing variance (+X.X%) exceeds your portfolio's tolerance
- Budget Lost IS (XX%) indicates spend potential
- CPA performance acceptable (within goal)
- Conservative X.X% increase per budget-recommendation-calculator methodology

Expected Outcome:
- Reduce pacing variance from +X.X% to within tolerance range
- Maintain acceptable CPA/ROAS performance
- Algorithm will ramp up over 3-5 days

{If NOT recommending increase:}
❌ Do NOT Increase Budget

Reason: {CPA over goal / Recent budget change / Low demand / etc.}
{Explanation using budget-recommendation-calculator decision tree}

QUALITY IMPROVEMENTS (if applicable):
{Secondary recommendations for quality score, ad relevance, etc.}

MONITORING:
{Items to watch over next 5-7 days}

Confidence Level: {High | Medium | Low}

================================================================================

---

Success Criteria

Investigation is successful if:

1. ✅ All six domain-knowledge companion skills auto-invoked at the start
2. ✅ Clear root cause identified with evidence
3. ✅ Diagnostic frameworks from the companion skills applied correctly
4. ✅ Specific, actionable recommendations (exact budget amounts, not "increase budget")
5. ✅ WHY the underspending is happening is explained (not just WHAT)
6. ✅ Diagnosis backed by data from script output
7. ✅ Investigation path adapted based on findings (stopped early if appropriate)

---

Important Notes

• Auto-invoke companion skills FIRST — load all six frameworks before analyzing script output
• Be autonomous — don't ask for permission at each step, just investigate
• Be adaptive — if Step 1 explains everything (ramp-up period), stop there
• Be specific — "Increase budget from $1,000 to $1,065 (+6.5%)" not just "increase budget"
• Be data-driven — every conclusion references script output metrics
• Be efficient — the script does the heavy lifting; you interpret and synthesize
• Reference frameworks — when explaining decisions, cite which framework was used

---

Invocation Patterns

Inline (single account, manual):

> "Use the underspending-investigation skill to investigate Example Property - Pmax. Pacing variance: +12.5%."

Parallel orchestration (used by a morning briefing orchestrator):

The orchestrator launches N parallel Task(subagent_type="general-purpose", …) calls in a single message, each with a prompt that invokes this skill against one account. Parallelism + per-investigation context isolation are preserved at the Task layer; the skill itself runs identically.

---

Companion Skills (Required)

All six are shipped in this repo as standalone skills:

• campaign-line-filtering — account-suffix → campaign-line filtering rules
• portfolio-pacing-rules — pacing thresholds and budget management philosophy (configure for your portfolios)
• google-sheets-lookups — sheet read patterns for pacing dashboards
• google-ads-query-patterns — GAQL templates for spend, IS, pacing, settings queries
• impression-share-diagnostics — IS decision tree and Pmax / Display caveats
• budget-recommendation-calculator — conservative budget calc methodology with decision tree

Install all six alongside this skill for full functionality.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fourteenwm
• Source: fourteenwm/ppc-ai-skills
• License: MIT

Install and usage instructions live in the source repository linked above.