Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(ads): add change impact review + cross-skill dedup (#38)

Tong Chen8ddbe09ed365
diff --git a/CHANGELOG.md b/CHANGELOG.md
index edd32770..04125a4c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
+## [0.11.3] — 2026-04-12
+
+### Added
+- **Change impact review mode** — Users can now say "check my changes" or "did my changes work" to review the impact of recent Google Ads changes. The ads skill routes these requests through session-checks with proper before/after metric comparison
+- **Maturation guidance** — When changes haven't had enough time to accumulate data (7 days for bid/keyword changes, 14 days for structural changes), the skill explains why and tells the user when to check back instead of showing misleading early metrics
+
+### Changed
+- **Deduped headline/description formulas** — Removed 50-line inline formula table from ads-copy SKILL.md; now references `rsa-best-practices.md` as single source of truth
+- **Deduped business context intake** — Removed 75-line duplicate intake procedure from ads-copy SKILL.md; now references `ads-audit/references/business-context.md` as canonical source
+- **Fixed session-checks query logic** — Changed from filtering only matured entries to finding all unreviewed entries, then branching on maturation status. Previously the "still maturing" message could never fire
+- **Removed overly generic triggers** — Dropped "did it improve" and "what happened after" which could false-positive on non-ads queries
+
+---
+
## [0.11.2] — 2026-04-11
### Changed
diff --git a/VERSION b/VERSION
index bc859cbd..1a96df19 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.11.2
+0.11.3
diff --git a/google-ads/ads-copy/SKILL.md b/google-ads/ads-copy/SKILL.md
index f423d1dd..25c52af2 100644
--- a/google-ads/ads-copy/SKILL.md
+++ b/google-ads/ads-copy/SKILL.md
@@ -24,83 +24,27 @@ These contain the specific formulas, character counts, and patterns that separat
## Business Context — Read First, Ask Once
-Every ad copy decision depends on understanding the business. This skill stores business context in `{data_dir}/business-context.json` so it only needs to be gathered once.
+Every ad copy decision depends on understanding the business. Business context is stored in `{data_dir}/business-context.json`.
### On every invocation:
-1. **Read `{data_dir}/business-context.json`**. If it exists and has content, use it — skip the intake interview.
-2. **If missing or empty**, run the intake interview below, then save the result.
+1. **Read `{data_dir}/business-context.json`**. If it exists and has content, use it — skip to the next section.
+2. **If missing or empty**, follow the full intake procedure in `../ads-audit/references/business-context.md` (website crawl, data bootstrapping, JSON schema). That document is the single source of truth for gathering business context.
3. **If the user volunteers new info** (new service, changed positioning, seasonal update), merge it into the existing file.
-### Intake interview
-
-Gather these fields. Don't ask them as a rigid checklist — pull what you can from context (the account's existing ads, campaign names) and only ask what's missing.
-
-**Website crawl before questions:** If you can find the business website URL from ad final URLs (via `listAds`) or the user provides it, issue `WebFetch` calls for the homepage, about page (`/about`, fallback `/about-us`), and services page (`/services`, fallback `/our-services`) in a single tool-use turn. Extract services, differentiators, social proof, offers, brand voice, and locations from the page content. Skip pages that 404 or return fewer than 50 words of visible text. If all pages fail, proceed to the full intake interview.
-
-```json
-{
- "business_name": "",
- "industry": "",
- "services": [""],
- "locations": [""],
- "target_audience": "",
- "brand_voice": {
- "tone": "",
- "words_to_avoid": [""],
- "words_to_use": [""]
- },
- "differentiators": [""],
- "competitors": [""],
- "seasonality": {
- "peak_months": [""],
- "slow_months": [""],
- "seasonal_hooks": [""]
- },
- "keyword_landscape": {
- "high_intent_terms": [""],
- "competitive_terms": [""],
- "long_tail_opportunities": [""]
- },
- "social_proof": [""],
- "offers_or_promotions": [""],
- "landing_pages": {},
- "notes": ""
-}
-```
-
-**Why each field matters for copy:**
+### How business context shapes copy
-| Field | How it shapes copy |
-|-------|-------------------|
-| `industry` | Sets baseline competitive intensity and CPC expectations |
+| Field | Copy application |
+|-------|-----------------|
| `services` | Determines headline categories and description angles |
| `locations` | Geo-specific headlines get higher quality scores and CTR |
| `brand_voice` | Tone, forbidden words, preferred language |
| `differentiators` | These ARE the value prop headlines — the reason someone picks you |
-| `competitors` | Knowing who you're against sharpens positioning (without naming them in ads) |
-| `seasonality` | Tells you WHEN to push urgency copy vs. evergreen, which months to bid up |
-| `keyword_landscape` | High-intent terms go in headlines; competitive terms need sharper differentiation; long-tail = cheaper, more specific copy angles |
-| `social_proof` | Reviews, awards, years in business — trust signal headlines and descriptions |
+| `competitors` | Sharpens positioning (without naming them in ads) |
+| `seasonality` | When to push urgency copy vs. evergreen |
+| `social_proof` | Trust signal headlines and descriptions |
| `offers_or_promotions` | Time-sensitive copy angles, CTA variations |
-| `landing_pages` | Copy must match the page or conversions drop — know what's there |
-
-### Bootstrapping from existing data
-
-Before asking the user anything, try to fill fields from what's already available. Start with account-level calls, then use campaign IDs from `listCampaigns` for per-campaign tools:
-
-1. **Account-level (parallel, no campaignId needed):**
- - `getAccountInfo` → business name, location hints
- - `listCampaigns` → service categories from campaign names, identify top campaigns by spend
-
-2. **Per-campaign (parallel, requires campaignId from step 1):**
- - `listAds(campaignId)` → current voice, headlines in use
- - `getKeywords(campaignId)` → keyword landscape
- - `getSearchTermReport(campaignId)` → real user language, long-tail opportunities
- - `getImpressionShare(campaignId)` → competitive pressure signals (max 90 days)
- - `getCampaignSettings(campaignId)` → geo targeting, network settings
-
-Present what you found and ask the user to confirm/correct/fill gaps. This is faster and more accurate than starting from zero.
+| `landing_pages` | Copy must match the page or conversions drop |
## Persona-Informed Copy
@@ -226,36 +170,9 @@ Google RSA: up to **15 headlines** (30 chars max) and **4 descriptions** (90 cha
**Always count characters. Flag any that exceed limits. A single character over = rejected by Google.**
-#### Headline Formulas by Category
-
-Use these formulas to generate varied, high-performing headlines. Each formula is battle-tested across thousands of accounts. Adapt the template to the specific business.
-
-| # | Category | Formula | Template | Example | Chars |
-|---|----------|---------|----------|---------|-------|
-| 1 | Service+Location | [Service] in [City] | `___ in ___` | Dog Boarding in Seattle | 23 |
-| 2 | Service+Location | [City] [Service] Provider | `___ ___ Provider` | Austin Plumbing Experts | 24 |
-| 3 | Service+Location | [Neighborhood] [Service] | `___ ___` | Capitol Hill Dog Boarding | 26 |
-| 4 | Value Prop | [Benefit] [Service] | `___ ___` | Same-Day AC Repair | 18 |
-| 5 | Value Prop | [Adj] [Service] [Qualifier] | `___ ___ ___` | Affordable Pet Grooming | 24 |
-| 6 | Value Prop | [Service] You Can Trust | `___ You Can Trust` | Plumbing You Can Trust | 22 |
-| 7 | Trust Signal | [N]+ Years Experience | `___+ Years Experience` | 25+ Years Experience | 20 |
-| 8 | Trust Signal | [Rating]★ Rated [Service] | `___★ Rated ___` | 4.9★ Rated Dog Boarding | 24 |
-| 9 | Trust Signal | [N]+ [Reviews/Clients] | `___+ 5-Star Reviews` | 500+ 5-Star Reviews | 21 |
-| 10 | CTA | Get [Benefit] Today | `Get ___ Today` | Get Your Free Quote Today | 25 |
-| 11 | CTA | Book [Service] Now | `Book ___ Now` | Book Your Cleaning Now | 22 |
-| 12 | CTA | Call Now — [Benefit] | `Call Now — ___` | Call Now — Free Estimate | 24 |
-| 13 | Urgency | [Offer] — Limited Time | `___ — Limited Time` | 20% Off — Limited Time | 23 |
-| 14 | Urgency | [N] Spots Left [Period] | `___ Spots Left ___` | 5 Spots Left This Week | 23 |
-| 15 | Price/Offer | [Service] From $[Price] | `___ From $___` | Teeth Cleaning From $99 | 24 |
-| 16 | Price/Offer | Free [Offer] Included | `Free ___ Included` | Free Consultation Included | 27 |
-| 17 | Question | Need [Service]? | `Need ___?` | Need Emergency Plumbing? | 24 |
-| 18 | Question | Looking for [Service]? | `Looking for ___?` | Looking for Dog Boarding? | 25 |
-| 19 | Benefit | [Result] Guaranteed | `___ Guaranteed` | Satisfaction Guaranteed | 23 |
-| 20 | Benefit | [Outcome] in [Timeframe] | `___ in ___` | Results in 30 Days | 19 |
-| 21 | Social Proof | Trusted by [N]+ [Clients] | `Trusted by ___+ ___` | Trusted by 500+ Families | 25 |
-| 22 | Social Proof | [City]'s Top-Rated [Service] | `___'s Top-Rated ___` | Seattle's Top-Rated Vet | 24 |
-| 23 | Differentiator | [Unique Feature] [Service] | `___ ___` | Licensed & Insured Pros | 23 |
-| 24 | Differentiator | [Guarantee] or [Refund] | `___ or ___` | On Time or It's Free | 20 |
+#### Headline & Description Formulas
+
+See `references/rsa-best-practices.md` — Headline Formula Table (27 formulas across 8 categories) and Description Formula Table (5 formulas). Use those as the source of truth for all copy generation.
**Headline selection rules:**
- Generate 3-4 headlines per category for a total of 12-15
@@ -264,19 +181,6 @@ Use these formulas to generate varied, high-performing headlines. Each formula i
- Leave Position 2 unpinned to let Google test Value Prop, Trust, and Differentiator headlines
- Never pin more than 3 headlines total — over-pinning reduces Google's optimization ability
-#### Description Formulas
-
-| # | Angle | Template | Example | Chars |
-|---|-------|----------|---------|-------|
-| 1 | Core Value + Location | [Primary benefit] for [audience] in [location]. [Secondary benefit]. [CTA]. | Professional dog boarding for Seattle pet parents. Cage-free play all day. Book online today. | 88 |
-| 2 | Differentiator + CTA | [What makes you different]. [Proof point]. [CTA with urgency]. | Family-owned since 2005 with 500+ 5-star reviews. Schedule your free estimate — limited availability. | 90 |
-| 3 | Trust + Social Proof | [Trust signal]. [Social proof]. [Outcome promise]. | Licensed, bonded & insured. Rated 4.9★ by 300+ homeowners. Your satisfaction guaranteed. | 85 |
-| 4 | Urgency + Offer | [Time-sensitive hook]. [Offer detail]. [CTA]. | This week only — 20% off your first visit. New clients save on [service]. Call now to claim. | 87 |
-| 5 | Problem + Solution | [Pain point]? [Solution]. [Proof]. [CTA]. | Tired of unreliable contractors? We show up on time, every time. 25+ years trusted. Get a quote. | 90 |
-| 6 | Feature Stack | [Feature 1]. [Feature 2]. [Feature 3]. [CTA]. | Same-day service. Transparent pricing. No hidden fees. Request your free quote online today. | 86 |
-| 7 | Persona-Targeted | [Persona pain point]. [How you solve it]. [Decision trigger]. | Busy schedule? We offer evening & weekend appointments. Book online in 60 seconds. | 80 |
-| 8 | Seasonal/Timely | [Seasonal hook]. [Relevant service]. [Urgency CTA]. | Spring is peak pest season — protect your home now. Licensed exterminators. Book this week. | 87 |
-
**Description selection rules:**
- Always generate 4 descriptions (the RSA maximum)
- D1 should be the strongest all-around description (core value + location) — it shows most often
diff --git a/google-ads/ads/SKILL.md b/google-ads/ads/SKILL.md
index 100839f7..86bc861c 100644
--- a/google-ads/ads/SKILL.md
+++ b/google-ads/ads/SKILL.md
@@ -22,6 +22,11 @@ triggers:
- rename campaign
- rename ad group
- bulk keywords
+ - check my changes
+ - did my changes work
+ - review my changes
+ - how are my changes doing
+ - change impact
---
## Setup
@@ -38,6 +43,13 @@ This skill handles two very different request types. Recognizing which one you'r
> 2. On approval: call `pauseKeyword`, log per `references/change-tracking.md`
> 3. Done. No session checks, no performance analysis.
+**Change impact review:**
+> User: "check my changes" / "did my changes work?" / "review my changes"
+> 1. Read `references/session-checks.md` and run the change review checks
+> 2. If no pending changes: tell the user no recent changes are logged
+> 3. If changes exist but review window hasn't passed: show maturation message (see `references/session-checks.md`)
+> 4. If ready for review: pull before/after metrics, compute deltas, show results
+
**Analysis request:**
> User: "how are my ads doing?"
> 1. Read `references/session-checks.md` and run those checks (pending reviews, anomalies)
diff --git a/google-ads/ads/references/change-tracking.md b/google-ads/ads/references/change-tracking.md
index 61178085..2d619fea 100644
--- a/google-ads/ads/references/change-tracking.md
+++ b/google-ads/ads/references/change-tracking.md
@@ -34,6 +34,6 @@ Append to the `changes` array:
- **Capture before-metrics** from data already in context. If none available: `"beforeSnapshot": { "metrics": null, "note": "No pre-change metrics" }`.
- **Review windows:** Bid/keyword/negative/budget changes: 7 days. Campaign creates/pauses/restructures/ad copy: 14 days.
-- **Tell the user:** "Change logged. I'll check the impact when you next open a session after [reviewAfter date]. You can also ask 'review my changes' anytime."
+- **Tell the user:** "Change logged. Google Ads changes typically take **7 days minimum** to show reliable results (14 days for structural changes like new campaigns or ad copy). I'll check the impact after [reviewAfter date] — you can also ask 'check my changes' anytime."
- **Max 200 entries** (remove oldest reviewed first).
- **Group related writes** in one session as a single entry.
diff --git a/google-ads/ads/references/session-checks.md b/google-ads/ads/references/session-checks.md
index 0fe86c49..5d428a45 100644
--- a/google-ads/ads/references/session-checks.md
+++ b/google-ads/ads/references/session-checks.md
@@ -1,12 +1,21 @@
# Session Start Checks
-Run these checks only when the user's request is analysis-oriented (performance reviews, optimization, "how are my ads", "show me", audits). Skip them for direct action commands like "pause keyword X", "rename campaign Y", "add negative keyword Z".
+Run these checks when the user's request is analysis-oriented (performance reviews, optimization, "how are my ads", "show me", audits) OR when the user explicitly asks to review their changes ("check my changes", "did my changes work"). Skip them for direct action commands like "pause keyword X", "rename campaign Y", "add negative keyword Z".
## Check for pending change reviews
-Read `{data_dir}/change-log.json`. Find entries where `reviewed` is `false` and `reviewAfter` date has passed.
+Read `{data_dir}/change-log.json`. Find entries where `reviewed` is `false`.
-If pending reviews exist:
+**If unreviewed changes exist but `reviewAfter` has NOT passed yet:**
+
+> **Changes still maturing:**
+>
+> _[Date]: [summary]_
+> Google Ads needs time to accumulate enough data for a reliable before/after comparison. Ready for review on [reviewAfter date] ([reviewWindow] review window per `change-tracking.md`).
+
+Do NOT pull metrics or attempt to assess impact early — small sample sizes lead to misleading conclusions.
+
+**If unreviewed changes exist AND `reviewAfter` has passed:**
1. Pull current metrics for affected campaigns using `listCampaigns` and `getCampaignPerformance` (7-day window). Use the `beforeSnapshot` from the change log as baseline — only fall back to `getCampaignPerformance` for the pre-change period if `beforeSnapshot.metrics` is null. Do this in parallel with the user's actual request. Save the `listCampaigns` result for reuse in anomaly detection.