opencode-knowledge-work 0.0.0-stage → 0.1.1

package/content/small-business/skills/small-business-ad-manager/reference/ad_copy.md

@@ -0,0 +1,112 @@
+# Ad Copy and Creative Briefs
+
+How to write ads that sound like the owner, and how to hand a visual off to Canva.
+
+Read [the shared voice profile](../../../shared/voice-profile.md) first. Ads carry the owner's name and their neighbors see them. Generic ad-speak in a local market is worse than no ad.
+
+---
+
+## Three variants, three different bets
+
+Draft three per ad slot. Each variant tests one thing, and you say what.
+
+| Variant | Tests |
+|---|---|
+| A | The offer — what is being promised |
+| B | The angle — the reason to care, usually a different pain |
+| C | The format — question versus statement, short versus specific |
+
+Three headlines that differ by a word teach nothing after USD 600 of spend. If the owner only wants one, give one and say which bet it is making.
+
+---
+
+## The structure that works for local service
+
+1. **Say who it is for, in their words.** "Bergen County homeowners" beats "valued customers."
+2. **Name the actual problem.** Specific beats broad. "AC quit in the middle of a heat wave" beats "HVAC issues."
+3. **Say what happens next.** A real, small next step.
+4. **One call to action.** Not three.
+
+Under 40 words for the body on most placements. People are scrolling.
+
+---
+
+## Worked example
+
+Okonkwo Mechanical, spring tune-up campaign. Ray's voice profile: short sentences, contractions, "the work" not "solutions," never "reach out."
+
+```
+Variant A — tests the offer
+  Headline:  USD 89 AC Tune-Up Before the First Hot Week
+  Body:      We check the whole system, clean the coils, and tell you
+             straight if anything's about to go. Takes about an hour.
+             Booking now for May.
+  CTA:       Book a time
+
+Variant B — tests the angle (fear of the July breakdown)
+  Headline:  Nobody Wants To Call Us In July
+  Body:      Most emergency calls we get in summer were fixable in spring
+             for a fraction of the cost. An hour now saves the 95-degree
+             phone call later.
+  CTA:       Book a time
+
+Variant C — tests the format (question, shorter)
+  Headline:  When Did You Last Have The AC Looked At?
+  Body:      If the answer is "no idea," it's time. USD 89, about an hour,
+             and a straight answer on what shape it's in.
+  CTA:       Book a time
+```
+
+All three sound like Ray. None uses a word he has never written.
+
+---
+
+## Rules that keep ads out of trouble
+
+- **Never invent a price, guarantee, discount, or credential.** If the owner has not said it, it does not go in the ad. This is a legal exposure, not a style preference.
+- **Never state a response time the owner cannot meet.** "We answer in 15 minutes" written into an ad becomes a promise they will be held to.
+- **Avoid superlatives the owner cannot back.** "Best in the county" invites a challenge and reads as noise.
+- **Match the ad to the landing page.** An ad promising USD 89 that lands on a page with no price is the fastest way to waste a budget.
+- **Watch platform rules.** Personal attributes, health claims, and before-and-after imagery are restricted on most platforms. A rejected ad wastes days.
+
+---
+
+## Creative briefs
+
+When Canva is connected, generate the asset. When it is not, the brief is the deliverable — hand it to the owner or their designer and it is complete work.
+
+```
+Creative brief — Spring Tune-Up, Variant B
+
+Message:      The July emergency call you can avoid in May
+Format:       Square 1080x1080 for feed, 1080x1920 for stories
+Visual:       Technician at an outdoor condenser unit, daylight, real work
+              clothes. Not stock-photo polished.
+Text on art:  "Nobody wants to call us in July"  — large, top third
+Secondary:    "USD 89 spring tune-up" — bottom, smaller
+Brand:        Okonkwo Mechanical logo bottom right. Navy and white.
+Avoid:        Cartoon thermometers, sweating-emoji visuals, stock smiling
+              families in living rooms
+Deliverables: Both sizes, PNG
+```
+
+Confirm brand colors, logo, and fonts against what the owner has actually used before. If none is on file, ask once and note it, rather than picking.
+
+---
+
+## Sizes worth having on hand
+
+| Placement | Size |
+|---|---|
+| Feed, square | 1080 x 1080 |
+| Feed, portrait | 1080 x 1350 |
+| Stories and Reels, TikTok | 1080 x 1920 |
+| Right column and misc | 1200 x 628 |
+
+Generate the square and the vertical at minimum. Vertical placements are where most of the cheap impressions live, and a square image stretched into a vertical slot looks like a mistake.
+
+---
+
+## After the ads run
+
+Come back with the variant comparison against the minimum volumes in `diagnostics.md` — 1,000 impressions and 15 results per variant before naming a winner. Then say what the winner taught, not just which one won: "the fear-of-July angle beat the price angle by 40%, so lead with consequence, not discount, in the next round."

package/content/small-business/skills/small-business-ad-manager/reference/change_playbook.md

@@ -0,0 +1,127 @@
+# Change Playbook
+
+The changes worth making, and the approval gate each one needs before it happens.
+
+Every change in this file spends, stops, or redirects the owner's money. Recommending one is free. Making one requires a fresh yes.
+
+---
+
+## The approval block
+
+Same shape every time, dollars first. The owner should be able to decide without scrolling.
+
+```
+Change:      <what, named exactly as it appears in the ad account>
+Costs today: <$ per month at current settings>
+After:       <$ per month after the change>
+Net:         <$ change per month, plus the expected effect on results>
+Reversible:  <Yes or No, and how>
+Proceed?
+```
+
+Rules that make this work:
+
+- **One change, one block, one yes.** Never bundle. An owner approving "the plan" has not approved five separate spends.
+- **Absolute dollars always.** A percentage may appear beside the dollars, never instead of them.
+- **Monthly, not daily.** Ad platforms speak in daily budgets; owners think in monthly bills. Convert, and show both when they differ meaningfully.
+- **State the expected loss too.** Saving USD 1,400 by pausing a campaign also stops roughly 12 leads a month. An owner who only hears the saving will be angry in three weeks.
+- **A yes expires.** If the conversation moves on and comes back, ask again.
+
+---
+
+## Budget changes
+
+**When to increase.** Cost per result is stable or improving, frequency is under 3, and the campaign has 30+ days of history. Increase by no more than 20-30% at a time — larger jumps reset the platform's learning and results get worse before they get better. Say this, because the owner will otherwise ask why not double it.
+
+**When to decrease.** Cost per result is 40%+ worse than the trailing average, or frequency is above 4 with falling CTR.
+
+**When to leave it alone.** Under the minimum volumes in `diagnostics.md`. Most weeks, the right answer is no change.
+
+```
+Change:      Increase daily budget on "Spring Tune-Up" from USD 60 to USD 75
+Costs today: USD 1,840 a month
+After:       USD 2,300 a month
+Net:         +USD 460 a month. At the current USD 54 per lead that's about 8 more
+             leads a month, if efficiency holds. It usually slips a little.
+Reversible:  Yes, immediately
+Proceed?
+```
+
+---
+
+## Pausing and restarting
+
+Pausing is the safest change and the one owners most want. It still needs a gate, because it stops lead flow.
+
+Never pause the only campaign producing results, even if it looks expensive, without saying plainly that it is the only one working.
+
+Restarting is not free either. A restarted campaign re-enters the learning period and performs worse for several days. Say so.
+
+---
+
+## Targeting changes
+
+Higher risk than budget changes, because the effect is not obvious and not instantly reversible in practice — the audience data resets.
+
+Worth doing:
+
+- **Narrowing geography** to the area the owner actually services. Money spent on people 90 minutes outside the service radius is pure waste and this is the single most common fixable leak in local accounts.
+- **Excluding existing customers** from acquisition campaigns.
+- **Widening an exhausted audience** when frequency is above 4 — a broader audience beats a new creative on a burnt one.
+
+Not worth doing: stacking narrow interest filters. Small audiences cost more per result and the platform's own targeting usually beats hand-built layers.
+
+```
+Change:      Narrow "Emergency Repair" geography from 50 miles to 25 miles
+Costs today: USD 860 a month, 7 leads, USD 123 each
+After:       Same USD 860 budget, spent on a tighter area
+Net:         No spend change. Roughly 30% of impressions were outside the
+             service area, so expect cost per lead to fall. Volume may dip
+             for a week while it re-learns.
+Reversible:  Yes, but the audience learning restarts
+Proceed?
+```
+
+---
+
+## Publishing a new ad
+
+**The highest-risk action in this skill.** It is public, it carries the owner's brand, and it begins spending money the moment it goes live.
+
+Before the gate, show the owner the complete ad exactly as it will appear: headline, body, image or brief, destination link, call to action, audience, and budget.
+
+```
+Change:      Publish new ad "Tune-Up — Straight Answer v2" to Spring Tune-Up
+Headline:    <exact text>
+Body:        <exact text>
+Image:       <the Canva asset, or the brief if Canva is not connected>
+Goes to:     <exact destination URL>
+Costs today: USD 0 — new ad
+After:       Shares the existing USD 1,840 monthly campaign budget
+Net:         No new spend. Splits budget with the 2 ads already running.
+Reversible:  Yes, pause any time
+Proceed?
+```
+
+Three checks before publishing, every time:
+
+1. **The destination link works** and goes where the ad promises. A broken link burns the whole budget on nothing.
+2. **Every claim in the copy is true.** Prices, guarantees, response times, licenses. The owner is legally responsible for what the ad says.
+3. **No claim the owner did not make.** Never invent a guarantee, a discount, or a credential to make the copy stronger.
+
+---
+
+## In CSV mode
+
+Same blocks, same dollars, same one-at-a-time discipline. The only difference is the last line: instead of "Proceed?" it is a click path.
+
+```
+To make this change:
+  1. Ads Manager, Campaigns tab
+  2. Click "Spring Tune-Up"
+  3. Edit, then Budget
+  4. Change Daily Budget from USD 60.00 to USD 75.00
+  5. Publish
+```
+
+Then offer to check back in two weeks and read the next export.

package/content/small-business/skills/small-business-ad-manager/reference/data_sources.md

@@ -0,0 +1,100 @@
+# Data Sources
+
+Where the numbers come from, how to get them without a connector, and how to reconcile the two stories they tell.
+
+---
+
+## Connectors
+
+| Source | Status | What to pull |
+|---|---|---|
+| Canva | Available | Creative asset generation from a written brief |
+| TikTok Ads | The native connected path (TikTok MCP) | Spend, impressions, clicks, results, cost per result — at campaign, ad group, and ad level |
+| Google Ads | No native connector — reached through a Zapier connection built with `build-connector`, offered once when the owner runs ads there | Whatever the connected Zapier actions expose. CSV export still works when no connection exists |
+| HubSpot | Optional but high value | Leads by source, deals closed by source — the truth check on platform claims |
+| QuickBooks, Shopify, Square | Optional | Revenue actually collected in the period |
+
+**Check before assuming.** If a TikTok call or a Zapier action fails, do not retry in a loop and do not stall. Say the path is not available, switch to the export path, and keep going. Never call a platform with no native connector directly — it runs through a built Zapier connection or a CSV.
+
+---
+
+## The CSV export path
+
+This is the common path. Treat it as the default, not the fallback.
+
+### What to ask for, in the owner's words
+
+- **Google Ads:** "In Google Ads, go to Campaigns, set the date range to last 30 days, click the download icon, choose CSV."
+- **TikTok:** "Ads Manager, Campaign tab, Export, last 30 days."
+
+Ask for 90 days too when the question is about trend rather than this month. Say why: "30 days tells us where we are, 90 tells us which way it's moving."
+
+### Reading the file
+
+Header names differ by platform and by export settings. Map, do not assume.
+
+| What you need | Common column names |
+|---|---|
+| Spend | `Amount spent (USD)`, `Cost`, `Total spent` |
+| Impressions | `Impressions`, `Impr.` |
+| Clicks | `Clicks (all)`, `Link clicks`, `Clicks` |
+| Results | `Results`, `Conversions`, `Leads`, `Purchases` |
+| Cost per result | `Cost per result`, `Cost / conv.` — or compute it |
+| Reach and frequency | `Reach`, `Frequency` |
+| Date range | Usually in a header row above the table, not a column |
+
+**Two traps in real exports.** First, `Results` can mean different things per campaign — one row's result is a lead form, another's is a page view. Check the `Result type` column if it exists; if it does not, say the results are not comparable across campaigns rather than summing them. Second, currency symbols and thousands separators arrive as text. Strip them before arithmetic.
+
+If a column you need is absent, name it: "This export has spend and clicks but no conversion column, so I can tell you what traffic cost and nothing about what it produced." Then offer the export setting that would include it.
+
+---
+
+## Reconciling platform numbers against the CRM
+
+The two will never match. The gap is information, not an error.
+
+**Why platforms report more:**
+
+- View-through conversions — someone saw the ad, did not click, bought later
+- Cross-device attribution the CRM cannot see
+- Attribution windows, often 7 days after a click and 1 day after a view
+- Each platform claims the same conversion when a customer touched several ads
+
+**Why the CRM reports fewer:**
+
+- The source field is blank on records created by hand
+- Phone calls and walk-ins carry no digital source at all
+- Form fills that never became a CRM record
+
+### The method
+
+1. Pull platform-reported results per campaign
+2. Pull CRM leads and closed deals with that source, over the same dates
+3. Show both, side by side, labeled by who reported them
+4. Give the owner one number to steer by — cost per closed job from the CRM — and label the platform figure as the optimistic bound
+
+### Report it like this
+
+```
+Paid social — Spring Tune-Up
+  Spend                      USD 1,840
+  Platform says              34 conversions, USD 54 each
+  CRM says                   19 leads tagged to it, 6 became jobs
+  Cost per real job          USD 307
+  The gap                    The platform counts people who saw the ad and called
+                             later. The CRM only counts what got tagged.
+                             Real number is probably between the two,
+                             closer to the CRM.
+```
+
+Never publish one blended figure. Owners forward these numbers to partners and lenders.
+
+---
+
+## When there is no tracking at all
+
+Plenty of small accounts run ads with no pixel and no conversion event. Clicks are the only signal.
+
+Say it plainly: "There's no conversion tracking on this account, so nobody — not me, not the platform — can tell you what these ads produced. We can compare cost per click across campaigns, which tells you which creative got attention, and that is all it tells you."
+
+Then offer the fix as the first recommendation, ahead of any budget change. Tracking before optimization; otherwise every later recommendation rests on nothing.

package/content/small-business/skills/small-business-ad-manager/reference/diagnostics.md

@@ -0,0 +1,89 @@
+# Diagnostics
+
+How to read an ad account without fooling yourself. Cutoffs, minimum volumes, and what each signal actually means.
+
+---
+
+## Minimum data before you draw a conclusion
+
+Small accounts produce noisy numbers. Most bad ad advice is a two-week swing read as a trend.
+
+| Decision | Minimum before you call it |
+|---|---|
+| Pause a campaign | 30 days, or 50 results, whichever comes first |
+| Declare a creative a winner | 1,000 impressions and 15 results per variant |
+| Call a cost-per-result trend real | 3 consecutive weeks in the same direction |
+| Judge a brand-new campaign | 7 days minimum — platforms need a learning period |
+| Shift budget between campaigns | 30 days of both running |
+
+Below these, say so: "Two weeks and 9 leads is not enough to call this. Here's what it looks like so far, and what I'd want before changing anything."
+
+Seasonality matters more than owners expect. An HVAC account in a July heat wave is not the same account in October. Compare to the same weeks last year when the data exists, and say when it does not.
+
+---
+
+## The metrics, and what they actually tell you
+
+| Metric | What it answers | Where it misleads |
+|---|---|---|
+| Spend | What it cost | Nothing on its own |
+| Impressions | How many times it showed | Rewards cheap, worthless audiences |
+| Frequency | Times the average person saw it | Above 3-4 in a month means the audience is exhausted |
+| CTR | Whether the creative earns attention | A great CTR to a bad landing page still produces nothing |
+| Cost per click | Cost of attention | Says nothing about quality |
+| Cost per result | The working number | Only meaningful if the result is defined the same way across campaigns |
+| Cost per closed job | The number that matters | Needs CRM data; often unavailable |
+| Return on spend | Revenue divided by spend | Only for commerce with reliable purchase tracking |
+
+Lead with cost per result when tracking exists. Lead with cost per closed job when the CRM can supply it. Never lead with impressions.
+
+---
+
+## Status cutoffs
+
+Relative to the account's own trailing 90-day average, not to an industry benchmark. Benchmarks from the internet do not know this owner's market.
+
+| Status | Rule |
+|---|---|
+| Working | Cost per result within 15% of the trailing average or better, volume steady or rising |
+| Watch | Cost per result 15-40% worse, or frequency above 3, or volume falling two weeks running |
+| Problem | Cost per result more than 40% worse, or spending with zero results for 14+ days |
+| No verdict | No conversion tracking, or below the minimum volume above |
+
+**No verdict is a real status.** Use it. It is far better than a confident judgment on nothing.
+
+---
+
+## The signals that carry real meaning
+
+**Rising spend with rising cost per result.** The audience is running out. More budget buys worse results, not more of the same. This is the most common misread in the whole discipline.
+
+**Frequency climbing while CTR falls.** Creative fatigue. The same people are seeing the same ad repeatedly and have stopped noticing. The fix is new creative, not more money.
+
+**Strong CTR with weak conversion.** The ad is doing its job; the landing page or the offer is not. Do not touch the ad.
+
+**One campaign carrying the account.** Check what share of results comes from the top campaign. Above 70% means the account is fragile — one policy flag or audience burnout takes the whole thing down.
+
+**Results steady, cost per result rising slowly.** Usually auction pressure — competitors bidding more — not a broken campaign. Says the channel is getting more expensive, which is a pricing conversation, not an optimization one.
+
+**Everything looks fine but the phone is quiet.** Trust the phone. Check whether the lead form is broken, whether leads are going to a mailbox nobody reads, and whether the tracking is double-counting.
+
+---
+
+## Worked read
+
+Okonkwo Mechanical, 30 days, paid social:
+
+```
+Account            USD 3,100 spent, 41 leads, USD 76 each
+                   Trailing 90-day average: USD 58 each. 31% worse. Watch.
+
+Spring Tune-Up     USD 1,840, 34 leads, USD 54 each. Frequency 2.1. Working.
+Emergency Repair   $   860,  7 leads, USD 123 each. Frequency 4.6. Problem.
+                   Frequency says this audience is used up, not that the
+                   offer is wrong.
+Brand Awareness    $   400,  0 leads. No conversion event on this campaign.
+                   No verdict — it was never set up to be measured.
+```
+
+The story in one sentence: the account looks 31% worse than usual, and almost all of that is one saturated campaign plus USD 400 a month going somewhere nobody is measuring.

package/content/small-business/skills/small-business-ad-manager/reference/gotchas.md

@@ -0,0 +1,181 @@
+# Gotchas
+
+Failure modes that waste an owner's ad budget. Every one of these has a dollar figure attached in the real world, which is why this skill gates execution so tightly.
+
+---
+
+## Gotcha: executing a percentage change without stating the dollars
+
+**Why it matters:** "Cut it by 30%" is a number the owner cannot feel. They approve it, then see the bill and realize they agreed to something they never pictured. Every executed change must state the absolute monthly dollars before and after.
+
+### Bad
+
+```
+Recommend reducing the retargeting budget by 30%. Proceed?
+```
+
+### Good
+
+```
+Change:      Reduce "Retargeting — All Visitors" daily budget
+Costs today: USD 1,200 a month (USD 40/day)
+After:       USD 840 a month (USD 28/day)
+Net:         Saves USD 360 a month. Expect roughly 4 fewer leads a month.
+Reversible:  Yes, immediately
+Proceed?
+```
+
+The percentage can stay. It just cannot travel alone.
+
+---
+
+## Gotcha: bundling changes behind one approval
+
+**Why it matters:** An owner who says yes to "the plan" has not said yes to five separate money decisions. Bundling is how a USD 400 adjustment turns into a USD 2,000 one that nobody remembers agreeing to.
+
+### Bad
+
+```
+Here's the plan: pause Emergency Repair, raise Spring Tune-Up to USD 75/day,
+narrow the geography, and publish two new ads. Sound good?
+```
+
+### Good
+
+Four separate blocks, four separate yeses, in priority order. Start with the one that saves money, since it is the easiest to approve and it funds the rest.
+
+If the owner says "just do all of it," restate the total dollar impact in one line and get a yes on that number specifically — "that's USD 860 saved and USD 460 added, net saving USD 400 a month, four changes. Confirm?"
+
+---
+
+## Gotcha: reporting one ROI number as fact
+
+**Why it matters:** Owners ask for "the exact ROI of every campaign." The honest answer is that no such number exists — the platform and the CRM measure different things and always disagree. A single confident figure is fiction, and owners take these numbers to lenders and partners.
+
+### Bad
+
+```
+Paid social ROI: 4.2x
+```
+
+### Good
+
+```
+Paid social — Spring Tune-Up, USD 1,840 spent
+  Platform reports 34 conversions
+  CRM shows       19 leads tagged to it, 6 closed, USD 9,400 in jobs
+  By the CRM      5.1x return, USD 307 per closed job
+  By its count    It would look better, because the platform counts people who saw
+                  the ad and called later without clicking.
+  Steer by        The CRM number. It's the conservative one and it's the
+                  one tied to money you actually collected.
+```
+
+---
+
+## Gotcha: recommending more spend on a channel that is saturating
+
+**Why it matters:** Rising spend with rising cost per result means the audience is running out. "It's working, spend more" is the most expensive wrong call in paid ads.
+
+### Bad
+
+```
+Spring Tune-Up drove 34 leads, up from 21. Recommend doubling the budget.
+```
+
+Spend went from USD 900 to USD 1,840 and cost per lead went from USD 43 to USD 54.
+
+### Good
+
+```
+Volume is up because spend is up. Cost per lead went from USD 43 to USD 54 over the
+same period, so each extra dollar is buying less. Raise it 20% at most, to
+USD 2,200 a month, and watch cost per lead for two weeks. If it holds under USD 60,
+raise again. If it crosses USD 65, the audience is done and new creative beats
+new budget.
+```
+
+---
+
+## Gotcha: judging a campaign that was never set up to be measured
+
+**Why it matters:** Plenty of campaigns run with no conversion event. Grading them on clicks produces a confident verdict about nothing, and budget moves off it.
+
+### Bad
+
+```
+Brand Awareness: 2,400 clicks at USD 0.17. Best performing campaign — scale it.
+```
+
+### Good
+
+```
+Brand Awareness: USD 400 spent, 2,400 clicks, zero conversion tracking. No
+verdict — this campaign was never set up to report results, so nobody can
+say what it produced. Cheapest clicks in the account, which usually means
+the cheapest attention. First recommendation is to add a conversion event,
+then give it 30 days.
+```
+
+---
+
+## Gotcha: publishing an ad with a claim the owner never made
+
+**Why it matters:** Ad copy is a public promise the owner is legally responsible for. An invented guarantee or price is a liability, not a creative flourish.
+
+### Bad
+
+```
+Headline: 100% Satisfaction Guaranteed — Same-Day Service, Always
+```
+
+Neither the guarantee nor the same-day promise exists anywhere in what the owner said.
+
+### Good
+
+```
+Headline: USD 89 AC Tune-Up Before the First Hot Week
+```
+
+Only what the owner actually offers. If a stronger claim would help, ask whether it is true rather than writing it and hoping.
+
+---
+
+## Gotcha: reading two weeks as a trend
+
+**Why it matters:** Small accounts swing hard week to week. Half of all "the ads stopped working" panics are normal variance, and reacting to them destroys the platform's learning and makes results genuinely worse.
+
+### Bad
+
+```
+Cost per lead jumped from USD 54 to USD 89 this week. Pause the campaign.
+```
+
+### Good
+
+```
+Cost per lead was USD 89 this week against a USD 54 average — but that's 6 leads on
+a rainy week, which is inside normal swing for this account. Nothing to do
+yet. If it stays above USD 70 for three straight weeks, that's real and we act.
+```
+
+---
+
+## Gotcha: treating the CSV path as a downgrade
+
+**Why it matters:** Most owners will not have an ad connector. If the export path feels like an apology, the skill is broken for the majority of the people using it.
+
+### Bad
+
+```
+I can't access your ad account, so I can only do a limited review.
+```
+
+### Good
+
+```
+No ad connector on this account, so we'll work from your export — same
+analysis either way. In your ads platform: export the last 30 days as a CSV,
+broken down by campaign. Send me that file and I'll have the read and the
+recommended changes back to you, with the exact clicks to make each one.
+```