opencode-knowledge-work 0.0.0-stage → 0.1.0

package/content/small-business/skills/small-business-review-reputation/reference/churn-signals.md

@@ -0,0 +1,110 @@
+# Quiet customers and win-backs
+
+Most customers do not complain before they leave. They just stop. Finding them
+is a data job, not a sentiment job.
+
+---
+
+## Set the rhythm per customer, not per business
+
+A customer is quiet when their gap has stretched well past *their own* normal
+interval. Comparing everyone to a single company-wide average produces a list
+full of annual customers who are perfectly happy.
+
+For each customer with three or more orders or jobs:
+
+```
+their normal interval = median gap between their own orders
+quiet                 = current gap > 2× their normal interval
+gone                  = current gap > 3× their normal interval
+```
+
+With fewer than three orders there is no rhythm to measure. Compare those to
+the business's median instead, and label them as an estimate in the report.
+
+| Customer | Normal interval | Current gap | Read |
+|---|---|---|---|
+| Dana R. | 3 months | 7 months | Quiet — worth a call |
+| Kirby St. LLC | 12 months | 13 months | Normal — leave alone |
+| M. Alvarez | 6 weeks | 5 months | Gone — win-back |
+
+---
+
+## Rank by what the relationship was worth
+
+Sort the quiet list by past value, not by length of silence. The owner has
+time for fifteen conversations, not two hundred, and the fifteen should be the
+ones that mattered.
+
+Value in order of usefulness: lifetime spend, then order frequency, then most
+recent order size. Use whatever the connected data actually supports and say
+which one you used.
+
+**The strongest signal is a pairing:** a customer who left a negative review
+and then stopped ordering. Flag those at the top regardless of value. They
+told the business exactly what was wrong and then left anyway, and they are
+the most winnable because the fix is already known.
+
+---
+
+## Shopify order patterns as sentiment
+
+Behavior leads reviews by weeks. Reading it early is the only chance to fix
+something before it becomes public.
+
+Worth surfacing:
+
+- **Fulfillment time drifting up** across a period. Compare the window to the
+  prior one and report both numbers.
+- **Repeat refunds against one product** or one date range. Three refunds on
+  the same SKU is a product problem, not three unhappy people.
+- **Partial or split shipments** rising. These generate "where is the rest of
+  my order" contacts a week or two later.
+- **First-order customers who never came back,** as a share of the window.
+
+Report what the data shows and nothing beyond it. If refund reasons are not
+recorded in the data, say they are unavailable rather than inferring why
+people asked for money back.
+
+---
+
+## Designing the win-back
+
+One message per customer, referencing something real: what they bought, what
+was fixed, the season their equipment gets serviced. Generic "we miss you"
+mail is exactly what they already delete.
+
+Confirm what the owner can actually honor before drafting. Never invent a
+discount, credit, free service, or priority slot. Ask:
+
+```
+Before I draft these — what's actually on the table for a win-back?
+
+  Something like a discount or a free check-up
+  A straight personal note with no offer
+  A call from you rather than an email
+
+For the four highest-value names I'd suggest the call. An email to someone
+who spent USD 9,000 with you reads as a mailing list.
+```
+
+**Offer strength by segment:**
+
+| Segment | What usually works |
+|---|---|
+| High value, left a bad review | A personal call. No offer up front — the apology is the offer |
+| High value, no complaint | A note from the owner, naming the last job |
+| Mid value, seasonal business | A timely reminder, no discount needed |
+| Low value, one-time buyer | A single low-cost offer, then stop |
+
+**Stop after one.** A second and third win-back attempt to someone who has not
+replied damages the brand and, for email, damages deliverability for everyone
+else. One good message, then leave them alone.
+
+---
+
+## Approval
+
+Every win-back is drafted for approval and sent one at a time. The owner
+approves the message and the offer inside it. An offer that goes out before
+the owner has agreed to honor it turns a churn problem into a refund problem.

package/content/small-business/skills/small-business-review-reputation/reference/examples/example-report.md

@@ -0,0 +1,150 @@
+# Worked example — Okonkwo Mechanical
+
+Ray Okonkwo asks: *"What are people saying about us? Our Google rating dropped
+and I don't know why."*
+
+HubSpot and PayPal are connected. Gmail is connected. No Shopify.
+Google reviews came from an export Ray downloaded; Yelp was read from the web.
+
+---
+
+## Review and Reputation — Apr 28 to Jul 27, 2026
+
+**Google rating: 4.3 (34 reviews), down from 4.6 in the prior 90 days.**
+Yelp shows 4.0 across 11 visible reviews. These are separate populations and
+are not averaged together.
+
+### Sources pulled
+
+```
+Google reviews (export)      14 in window
+Yelp (web, partial)           6   — page shows most recent only
+PayPal disputes               2
+HubSpot tickets               9
+Gmail threads                11
+Shopify orders                —   not connected
+```
+
+Yelp is partial: the public page paginates and older reviews were not
+readable. The Google export is complete for the window.
+
+---
+
+### Themes
+
+**1. Parts waits with no updates (11 signals)**
+
+> "Waited nine days for a part and had to call three times to get an update."
+> — [Google, 1★, Jul 12]
+
+> "Nobody told us the part was backordered. We found out when we called."
+> — [HubSpot ticket, Jun 30]
+
+> "Still no word on the blower. Third week." — [Gmail, Jul 3]
+
+**2. Scheduling double-bookings (6 signals)**
+
+> "They booked us Thursday, then called Thursday morning to move it."
+> — [Google, 3★, Jun 18]
+
+> "Great install, terrible scheduling. Two reschedules." — [Yelp, 3★, Jul 2]
+
+**3. The techs themselves, consistently praised (9 signals)**
+
+> "Marcus went into a crawlspace I wouldn't send anyone into. Runs perfect."
+> — [Google, 5★, Jul 20]
+
+> "Whoever came out actually explained what was wrong. Rare." — [Gmail, Jun 12]
+
+The rating drop is not about the work. Every low review in the window is about
+waiting or scheduling; the work itself is what people compliment.
+
+---
+
+### Reviews needing a response
+
+Three unanswered, oldest first.
+
+```
+★★★☆☆  Google · Jun 18 · T. Whitfield
+"They booked us Thursday, then called Thursday morning to move it."
+
+Draft reply:
+  Moving a Thursday job on Thursday morning isn't good enough, and that
+  one's on us. We've gone to confirmation calls the day before so it
+  doesn't happen again. Thanks for the honest note. — Ray
+
+Post this, edit it, or skip it?
+```
+
+```
+★☆☆☆☆  Google · Jul 12 · Dana R.
+"Waited nine days for a part and had to call three times to get an update."
+
+Draft reply:
+  Nine days for a blower motor is too long, and you shouldn't have had to
+  chase us for updates. We've changed how we order parts so this doesn't
+  repeat. Call me at 555-0142 and I'll make the wait right. — Ray
+
+Post this, edit it, or skip it?
+```
+
+```
+★★★★★  Google · Jul 20 · L. Okafor
+"Marcus went into a crawlspace I wouldn't send anyone into. Runs perfect."
+
+Draft reply:
+  Thanks — I'll pass that to Marcus. He mentioned that crawlspace. Give us
+  a shout when it's time for the fall check. — Ray
+
+Post this, edit it, or skip it?
+```
+
+Ray approves all three, one at a time. The Jul 12 reply is edited first: he
+changes "we've changed how we order parts" to "we now order the part before
+the tech leaves," because that is what actually changed. That correction goes
+into the voice profile notes.
+
+---
+
+### Quiet customers
+
+Ranked by lifetime spend. Rhythm is each customer's own median gap between
+jobs, so annual customers are not on this list.
+
+| Customer | Normal | Current gap | Lifetime | Note |
+|---|---|---|---|---|
+| Dana R. | 3 months | 7 months | USD 9,140 | Left the Jul 12 one-star |
+| M. Alvarez | 6 weeks | 5 months | USD 4,300 | Last job was a reschedule |
+| Bellhaven Apts | 4 months | 9 months | USD 3,880 | No complaint on file |
+
+Dana is first regardless of value: she told the business what was wrong and
+then stopped. That pairing is the clearest churn signal in the data.
+
+Before drafting anything:
+
+```
+What's on the table for a win-back?
+
+  Something like a discount or a free check-up
+  A straight personal note with no offer
+  A call from you
+
+For Dana I'd suggest the call rather than an email. She spent USD 9,000 with
+you and just left a one-star — an email reads as a mailing list.
+```
+
+Ray picks the call for Dana, a note for the other two, and authorizes a free
+fall check-up for Bellhaven. Nothing is drafted until he says so, and nothing
+sends until he approves each message.
+
+---
+
+### Do these three things this week
+
+1. **Call Dana R.** She is the highest-value quiet customer and the parts wait
+   is why. Her review is also the one dragging the Google average.
+2. **Order parts before the tech leaves.** Eleven signals across three sources
+   trace to the same gap, and it is the whole reason the rating moved.
+3. **Confirm every job the day before.** Six scheduling signals, all
+   preventable with one phone call per job.

package/content/small-business/skills/small-business-review-reputation/reference/gotchas.md

@@ -0,0 +1,164 @@
+# Gotchas — review-reputation
+
+## Gotcha: Posting a public response without approval
+
+**Why it matters:** A review response is permanent, public, and attributed to
+the owner by name. It is read by every future customer who finds the review.
+There is no version of "we'll fix it next run" that undoes it.
+
+### ✗ Bad
+
+Draft eight responses, post them all, then show the owner what went out.
+
+### ✓ Good
+
+Present each draft next to the review it answers and get a yes on that one
+before posting it. Approve one at a time — a batch approval on eight public
+responses is how the wrong one goes live.
+
+---
+
+## Gotcha: Blending rating averages across platforms
+
+**Why it matters:** Google's 4.3 and Yelp's 4.0 describe different populations
+of reviewers. An average of the two is a number that exists nowhere, and the
+owner will repeat it to a customer or put it on a truck.
+
+### ✗ Bad
+
+> Your overall rating is 4.2 across 45 reviews.
+
+### ✓ Good
+
+> Google: 4.3 (34 reviews), down from 4.6 last quarter.
+> Yelp: 4.0 (11 visible). Different reviewer pools — not averaged.
+
+---
+
+## Gotcha: Treating a partial web scrape as a complete pull
+
+**Why it matters:** Public review pages paginate, truncate, and reorder. A
+report built on the first page reads as the whole picture, so the owner
+concludes there are no new complaints when there are three on page two.
+
+### ✗ Bad
+
+> Yelp reviews: 6
+
+### ✓ Good
+
+> Yelp (web, partial): 6 — page shows most recent only
+
+Then ask for an export once. It takes the owner two minutes and fixes every
+run afterward.
+
+---
+
+## Gotcha: Ranking quiet customers by silence alone
+
+**Why it matters:** A list sorted by longest gap fills with annual customers
+who are perfectly happy and one-time buyers who were never coming back. The
+owner works the top of the list, finds it worthless, and stops using it.
+
+### ✗ Bad
+
+Sort every customer by days since last order and hand over 200 names.
+
+### ✓ Good
+
+Measure each customer against their own median interval, then rank by past
+value. Fifteen names the owner will actually call beats two hundred they
+won't. Put anyone who left a bad review and then went quiet at the top
+regardless of value — they said what was wrong and left anyway.
+
+---
+
+## Gotcha: Offering a discount the owner never authorized
+
+**Why it matters:** A win-back message that promises 20% off is a commitment
+the owner has to honor once it lands. Drafting it before asking turns a churn
+problem into a margin problem, and the owner finds out when the customer
+redeems it.
+
+### ✗ Bad
+
+> Hi Dana — we've missed you. Here's 20% off your next service.
+
+Nobody agreed to 20%.
+
+### ✓ Good
+
+Ask what is on the table before drafting: an offer, a plain note, or a call
+from the owner. Draft only inside that answer, and say plainly when a call
+beats a coupon — an email to someone who spent USD 9,000 reads as a mailing list.
+
+---
+
+## Gotcha: Arguing with a reviewer in public
+
+**Why it matters:** The audience is not the reviewer. It is the next customer
+reading the exchange, deciding how this business behaves when provoked. A
+correct, well-evidenced rebuttal still loses that reader.
+
+### ✗ Bad
+
+> Our records show the technician arrived within the scheduled window and our
+> policy clearly states parts orders take 5-7 business days.
+
+### ✓ Good
+
+Correct one factual point, offer a real contact route, and stop. Under 60
+words. If the review breaks platform rules, explain the removal path to the
+owner honestly — including that most requests are declined — rather than
+promising it will come down.
+
+---
+
+## Gotcha: PayPal rate limits on dispute queries
+
+**Why it matters:** PayPal's disputes API throttles aggressively on date windows with many disputes. Silent retries burn the user's time with no feedback.
+
+### ✗ Bad
+Retry 3× automatically with no feedback. User sees a spinner for 30+ seconds before an error.
+
+### ✓ Good
+On the first rate-limit error, skip PayPal, add `PayPal: rate-limited — not included` to the Sources section, and continue with the remaining connectors. Mention that the user can try again with a narrower date window.
+
+---
+
+## Gotcha: Verbatim quotes paraphrased or summarized
+
+**Why it matters:** The owner needs to see the actual customer words — not Claude's interpretation. Paraphrase destroys the credibility of the report.
+
+### ✗ Bad
+**Theme: Slow shipping** (8 signals)
+> Customers reported that deliveries arrived later than expected.
+
+### ✓ Good
+**Theme: Slow shipping** (8 signals)
+> "Ordered 2 weeks ago and still nothing — this is unacceptable." — [Gmail]
+> "Package was 10 days late and support never responded." — [Zoho Desk]
+
+---
+
+## Gotcha: HubSpot returning 0 tickets treated as an error
+
+**Why it matters:** Test portals and new accounts legitimately have 0 tickets. Surfacing a warning creates noise and erodes trust.
+
+### ✗ Bad
+> ⚠️ HubSpot returned 0 tickets. Check your connection or permissions.
+
+### ✓ Good
+Record `HubSpot tickets: 0` in the Sources section and continue. Only flag a connector issue if authentication itself fails.
+
+---
+
+## Gotcha: Gmail keyword list too narrow
+
+**Why it matters:** Customers don't use standard complaint keywords. A 1-star experience often surfaces as "took forever" or "never again," not "disappointed."
+
+### ✗ Bad
+Search only for: `refund cancel unhappy`
+
+### ✓ Good
+Use the full seed list in `sources.md`, which includes phrasings like "took forever" and "never again." Let theme extraction filter signal from noise — over-inclusion is cheaper than a missed theme.

package/content/small-business/skills/small-business-review-reputation/reference/response-patterns.md

@@ -0,0 +1,123 @@
+# Review responses
+
+Every response is drafted for approval and posted only after the owner reads
+it. A public response cannot be taken back.
+
+Read `../../../shared/voice-profile.md` before drafting. These go out under the
+owner's name, in public, permanently. A guessed voice is worse here than
+anywhere else in the plugin.
+
+**Under 60 words.** A long reply reads as arguing, whatever it says.
+
+---
+
+## Negative review
+
+Four parts, in order:
+
+1. **Name the specific thing.** Not "we're sorry for your experience."
+   "You waited nine days for a part" — the reviewer needs to see they were
+   read.
+2. **Say what changed,** if anything genuinely did. If nothing has, skip this
+   rather than inventing a policy.
+3. **Move it offline with a real route.** A name and a number, not "please
+   contact us."
+4. **Stop.** No policy explanation, no context about how busy the season was.
+
+### ✗ Bad
+
+> We're sorry you feel this way. Our records show the technician arrived
+> within the scheduled window and our policy clearly states that parts
+> orders can take 5-7 business days. We pride ourselves on customer service
+> and hope you'll give us another chance.
+
+Defensive, cites policy at someone who is upset, and reads as a rebuttal to
+every future customer who finds it.
+
+### ✓ Good
+
+> Nine days for a blower motor is too long, and you shouldn't have had to
+> chase us for updates. We've changed how we order parts so this doesn't
+> repeat. Call me directly at 555-0142 and I'll make the wait right.
+> — Ray
+
+---
+
+## Positive review
+
+Short, specific, and clearly written by a person. Thank them for the thing
+they actually mentioned. A copy-pasted "Thanks for the 5 stars!" under
+fourteen reviews in a row tells every reader the responses are automated.
+
+### ✓ Good
+
+> Thanks Dana. Marcus said the crawlspace was a tight one — glad it's running
+> right. Give us a shout when it's time for the fall check.
+> — Ray
+
+---
+
+## Mixed review
+
+Answer both halves honestly. Owners tend to reply only to the compliment,
+which reads as ducking the complaint.
+
+### ✓ Good
+
+> Thanks for the kind words about the install. You're right about the
+> scheduling — we double-booked that Thursday and you paid for it. We've
+> moved to same-day confirmation calls since. — Ray
+
+---
+
+## Unfair or false review
+
+Stay calm, correct the one factual point, and stop. The audience is not the
+reviewer; it is the next customer reading the exchange, and they are watching
+how the business behaves under provocation.
+
+### ✓ Good
+
+> We don't have a record of a service call at this address, so this may be a
+> mix-up with another company. If we did work for you, call me at 555-0142
+> and I'll sort it out. — Ray
+
+**Escalation.** Removal is worth requesting only when a review clearly breaks
+the platform's rules — wrong business, no actual transaction, personal
+attacks, or an obvious conflict of interest. Explain to the owner what the
+platform's bar actually is, that most requests are declined, and that a calm
+public reply usually does more good than a removal fight. Never tell the owner
+a review will be removed; the platform decides.
+
+---
+
+## Approval flow
+
+Present each draft with the review it answers, so the owner judges them
+together:
+
+```
+★☆☆☆☆  Google · Jul 12 · Dana R.
+"Waited nine days for a part and had to call three times to get an update."
+
+Draft reply:
+  Nine days for a blower motor is too long, and you shouldn't have had to
+  chase us for updates. We've changed how we order parts so this doesn't
+  repeat. Call me directly at 555-0142 and I'll make the wait right. — Ray
+
+Post this, edit it, or skip it?
+```
+
+Approve one at a time. A batch approval on eight public responses is how a
+wrong one goes live.
+
+---
+
+## Timing
+
+Respond to negative reviews within a couple of days. A complaint answered
+promptly reads as a business paying attention; the same words a month later
+read as damage control.
+
+Do not respond to a review the owner has already answered. Check for an
+existing owner response before drafting anything.

package/content/small-business/skills/small-business-review-reputation/reference/sources.md

@@ -0,0 +1,116 @@
+# Sources
+
+One required backbone, everything else deepens it. The skill works on day one
+with nothing connected at all.
+
+| Source | Status | What it gives |
+|---|---|---|
+| A CRM (HubSpot, Monday.com, Salesforce, Zoho CRM), a payments connector (PayPal, Square, Stripe), **or** a storefront (Shopify, Square) | Required — one of any of the three categories | Tickets and feedback; disputes and refunds; or order history (who bought what and when) plus fulfillment and refund patterns |
+| Support desk (Zoho Desk) | Optional | Tickets by customer, priority, and status — complaints in the customer's own words |
+| Gmail | Optional | Complaint and praise language in threads |
+| Web research | Always available | Publicly visible reviews on Google, Yelp, Facebook |
+| Pasted or exported reviews | Always available | The best source there is, with dates and ratings |
+
+---
+
+## Public reviews
+
+**Preferred: an export.** Google Business Profile and Yelp both let the owner
+download their reviews. An export carries the rating, date, reviewer name, and
+full text, and it includes reviews the public page paginates away. Ask for one
+the first time this skill runs; it takes the owner two minutes and improves
+every run afterward.
+
+**Fallback: what is visible on the web.** Fetch the business's public review
+pages and read what renders. This is genuinely useful and genuinely partial —
+pages truncate, paginate, and reorder. Say so in the Sources section rather
+than presenting a partial pull as a complete one.
+
+**Also fine: pasted text.** The owner drops reviews into the chat. Tag them
+`[Review]` like any other source and use them.
+
+When counting, never total a rating average across sources. Google's average
+and Yelp's average are different numbers about different populations, and an
+owner who repeats a blended figure to a customer will be wrong.
+
+---
+
+## Disputes and tickets
+
+**PayPal disputes.** Fetch disputes opened in the window. PayPal throttles
+aggressively on wide date windows. On the first rate-limit error, stop, record
+`PayPal: rate-limited — not included` in Sources, and continue. Do not retry
+silently; suggest a narrower window instead.
+
+**Stripe disputes and refunds.** `GET /v1/disputes` created in the window
+(via `stripe_api_read`), with `reason` and `status`; `GET /v1/refunds` for
+the same window, since a run of refunds against one product is a theme
+before it is a review. A dispute's `evidence_details.due_by` is a deadline —
+surface any open one in the "do these three things" list.
+
+**Square disputes.** The disputes endpoint through `make_api_request` for the
+window. Same treatment as Stripe.
+
+**HubSpot tickets and feedback.** Fetch open and recently closed tickets, plus
+any feedback submissions. Zero tickets is a legitimate state for a new or
+small portal — record `HubSpot tickets: 0` and move on. Only flag a connector
+problem when authentication itself fails.
+
+**Zoho Desk tickets.** `getTickets` for the window (`receivedInDays` 30 or
+90 to match it; sort by `recentThread`), then `getThreads` on the ones whose
+subject reads as a complaint, for the verbatim. `getTicketsMetrics` gives the
+open, overdue, and on-hold counts for the header. Open tickets with priority
+High belong in the Disputes and tickets count, not only in the theme list.
+`getTickets` rejects an `include` parameter — ask for extra fields with
+`fields`.
+
+---
+
+## Email
+
+Search the window for threads containing complaint and praise language. Seed
+list, deliberately wide:
+
+```
+refund  cancel  unhappy  issue  problem  disappointed  frustrated  broken
+late  slow  wrong  missing  never again  took forever  thank you  lifesaver
+recommend  great job
+```
+
+Customers rarely use the word "disappointed." They write "took forever" and
+"never again." Over-inclusion is cheap here because theme extraction filters
+the noise; a narrow keyword list silently loses whole themes.
+
+Pull the subject line and one or two sentences of the customer's own words —
+enough to quote verbatim later.
+
+---
+
+## Shopify
+
+Covered in `churn-signals.md`. In short: orders, fulfillment times, and
+refunds, read as behavior rather than opinion.
+
+---
+
+## Reporting what you got
+
+Every run ends with an honest Sources block. Counts, and named failures:
+
+```
+Sources pulled — Apr 28 to Jul 27
+
+  Google reviews (export)      14
+  Yelp (web, partial)           6   — page shows most recent only
+  Stripe disputes               3
+  Stripe refunds                7
+  HubSpot tickets               0
+  Zoho Desk tickets            12   — 2 open, priority High
+  Gmail threads                11
+  Shopify orders              182
+```
+
+Name the connector that was actually read on each line (the example above is
+a Stripe and Zoho Desk shop; a PayPal and HubSpot shop lists those). The dash
+matters as much as the numbers. A source that is missing looks exactly like a
+source with nothing bad in it unless it is named.