opencode-knowledge-work 0.0.0-stage → 0.1.1

package/content/small-business/skills/small-business-outreach-composer/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: outreach-composer
+description: >
+  Writes prospect outreach and follow-up sequences that sound like the owner
+  wrote them, not like an AI did. Learns a voice profile from the owner's own
+  sent mail, grounds every message in something specific about that prospect,
+  builds the follow-up sequence behind it, queues every send for approval, and
+  logs each touch to the CRM. Runs draft-only when no mail connector is
+  available, so the copy can be pasted anywhere. Use this whenever the owner
+  needs to reach out to prospects or customers — including phrasings like
+  "write this cold email," "draft a follow-up," "reach out to these leads,"
+  "what do I say to them," "I need a sequence for this list," "nudge the people
+  who didn't reply," or "write it but don't make it sound like a robot." Reach
+  for it whenever outreach copy is the deliverable, even for a single message.
+allowed-tools: Read, WebFetch
+---
+
+# Outreach Composer
+
+Write outreach the owner would actually send under their own name.
+
+The single most repeated condition owners set is some version of "without sounding like a bot." Owners will not send copy that embarrasses them, so a message that reads as generated is worth nothing regardless of how well structured it is. Voice fidelity is the product here, not a finishing touch.
+
+## Step 1 — Learn the voice before writing anything
+
+Read [the shared voice profile](../../shared/voice-profile.md) first. If a profile already exists there, use it and skip to Step 2 — rebuilding it every time wastes the owner's patience and produces drift.
+
+If there is no profile, build one from evidence:
+
+- **Gmail or Microsoft 365** — pull 15 to 30 of the owner's own sent messages to customers and prospects. This is the best source by a wide margin. Confirm the mailbox is the owner's first (`../../shared/tenant-scope.md`); another tenant's sent mail would teach the wrong voice.
+- **HubSpot** — logged emails and notes
+- **Their website and any published writing** — weaker, but real
+- **Pasted examples** — ask for three emails they were happy with
+
+Then extract the specific, imitable traits: sentence length, greeting and sign-off habits, contractions, whether they use exclamation marks, how direct the ask is, what they call their own product, regionalisms, and the things they never do. Save the profile so every later run inherits it.
+
+**Without any sample, say so and ask for three.** Writing in a guessed voice produces exactly the generic copy the owner is trying to avoid.
+
+## Step 2 — Ground each message in something real
+
+A personalized email is not one with the company name merged into a template. It is one that could only have been sent to that person.
+
+For each prospect, find the specific hook. In order of strength:
+
+1. The buying signal from `lead-finder` — a permit filed, a location opened, a role posted
+2. A shared connection or customer
+3. Something specific about their business the owner can genuinely speak to
+4. A relevant result the owner produced for a similar customer
+
+If no hook exists beyond category fit, write a shorter, plainly cold message and say it is cold. A fake-warm opener is worse than an honest cold one, because it reads as a mail merge and destroys credibility in the first line.
+
+**Apollo or Clay, when connected, can fill in the contact and company detail that makes a thin hook usable** — role, tenure, company size, tech stack — the kind of specific that keeps a message from reading as generic. Enrichment data, not a hook on its own.
+
+## Step 3 — Write the sequence
+
+Read `reference/sequence_patterns.md` for structure by scenario. Defaults:
+
+- **Cold outreach** — 4 messages over 3 weeks
+- **Warm or referral** — 3 messages over 2 weeks
+- **Post-meeting follow-up** — 2 messages over 10 days
+- **Re-engagement of a quiet customer** — 3 messages over 4 weeks
+
+Each message in a sequence must add something new. A follow-up whose entire content is "just bumping this" trains people to ignore the sender. Give every touch a fresh reason to exist: a different angle, a relevant result, a genuinely useful piece of information, or a clean close-out.
+
+Length rule: first message under 120 words. Owners in this segment sell to people who read on their phone between jobs.
+
+## Step 4 — Self-check against the slop test
+
+Before showing anything, run every draft against `reference/slop_test.md`. It catches the specific patterns that make copy read as machine-written.
+
+The fastest checks:
+
+- Would the owner say this sentence out loud? If not, rewrite it.
+- Could this message be sent to any other company with two words changed? If yes, it is not personalized.
+- Does it open with a compliment about the prospect's business? Delete it — everyone does this and everyone recognizes it.
+- Is there a phrase here the owner has never used in their life? Cut it.
+
+This step is not optional and it is not a formality. It is the difference between copy that gets sent and copy that gets rewritten by hand, which is the outcome the skill exists to prevent.
+
+## Step 5 — Present for approval
+
+Show the full sequence before anything queues. Follow `reference/output_template.md`.
+
+Present message one in full, then the rest of the sequence with subject lines and the angle each takes. Owners want to read the first one closely and skim the shape of the rest.
+
+**Deliver per the owner's stored output preference — never default to a markdown file.** Check the `## Business context` block's `Output preference` (shared style guide rule, `../../shared/artifact-style.md`):
+
+- **Visual artifact (the default):** an HTML page in the house style — one card per prospect or sequence, each message as a copy block so any single message can be copied and sent by hand.
+- **docx / md / notion / canva preference:** deliver the same content in that form — a DOCX or markdown file, a Notion page created via the connector (named destination, never overwriting), or a Canva Doc created via the Canva connector (a new design each run, named with the date; tables become lists); fall back to the visual artifact if Notion or Canva is not connected — and say that is why.
+- **Best for skill:** use the visual artifact — the copy blocks are the point.
+
+Chat keeps the recap and the approval question in every case.
+
+Then ask what to change. Expect edits — the first pass is a proposal, not a delivery. Fold every edit back into the voice profile, because a correction made once should not have to be made again.
+
+## Step 6 — Queue sends, with approval, one gate at a time
+
+Sending email under the owner's name is the highest-consequence action in this skill.
+
+- **Never send without an explicit yes** for that specific batch
+- **State exactly what will happen** before asking: how many messages, to whom, on what schedule, from which account
+- **Never send to a contact marked "inferred"** without flagging it separately. Bounces at volume damage the owner's sending domain for months, and that damage reaches their real customer mail
+- **Approval for message one is not approval for the sequence.** Confirm the follow-ups separately, or set them to draft and let the owner release each
+
+**Mailchimp is a drafting destination, not a send route.** When it is connected, an approved
+sequence can be saved into Mailchimp as campaign content for the owner to schedule there.
+Three things govern that:
+
+- **It cannot send.** Nothing this skill puts into Mailchimp goes out on its own. The owner presses send in Mailchimp.
+- **Its planner refuses single campaigns.** Mailchimp's campaign planner only produces multi-channel plans — email plus SMS plus social. A one-off email is written here, in the owner's voice, and saved as content. Do not route a single message through the planner and do not report a refusal as a failure.
+- **Do not assume you can read the audience list.** Treat the contact list as unavailable unless a call actually returns it. Build the recipient list from the CRM or the owner's own file, as today.
+
+**Without a mail connector, run draft-only.** Produce the copy formatted to paste anywhere. This is a complete outcome, not a degraded one — plenty of owners prefer to send from their own client anyway.
+
+## Step 7 — Log it
+
+Log every touch to HubSpot when connected: what was sent, when, to whom, and where it sits in the sequence. Without a CRM, keep the record in a file so the next run knows who has already been contacted.
+
+Contacting someone twice with the same opener is a visible, avoidable mistake.
+
+## What not to do
+
+- **Do not write before learning the voice.** Everything downstream depends on it.
+- **Do not open with flattery about their business.** It is the single clearest tell.
+- **Do not send a follow-up that says only "checking in."** Every touch earns its place.
+- **Do not merge a company name into a template and call it personalized.**
+- **Do not send anything without an explicit approval for that batch.**
+- **Do not claim results the owner has not actually produced.** Invented case studies in outreach are a serious problem, not an exaggeration.
+
+## After the send
+
+The sequence is approved, queued or drafted, and every touch is logged. The natural next step is "update the CRM" — `crm-autopilot` keeps the next-step queue current as replies come in. Also nearby: "leads are going cold" (`speed-to-lead`) to catch the responses fast, and "find me customers" (`lead-finder`) when this list runs dry. Offer at most three, and skip any offer the owner already declined this session.
+
+## Reference files
+
+- [`../../shared/voice-profile.md`](../../shared/voice-profile.md) — the owner's voice, shared by every skill that writes in their name
+- `reference/sequence_patterns.md` — structure and cadence by scenario
+- `reference/slop_test.md` — the checklist that catches machine-written copy
+- `reference/output_template.md` — how sequences are presented for approval
+- `reference/gotchas.md` — the failure modes that get owners to stop using this
+
+## Using a tool that isn't listed
+
+The connectors named in this skill are the tested paths, not a wall. If the owner wants this flow to use a tool that isn't connected or listed, offer `build-connector` — it checks the connector directory first and connects through Zapier otherwise, never hand-building against a raw API. Once the connection exists, the tool joins this skill like any other optional connector, under the same approval gates.

package/content/small-business/skills/small-business-outreach-composer/reference/gotchas.md

@@ -0,0 +1,213 @@
+# Gotchas
+
+The failure modes that get an owner to stop using this skill after one bad draft.
+
+---
+
+## Gotcha: writing before learning the voice
+
+**Why it matters:** The first draft is where trust is won or lost. A generically competent email confirms the owner's fear that this will sound like a bot, and they go back to writing by hand.
+
+### Bad
+
+```
+Owner: "Write these 12 prospects an intro email."
+Claude: [writes a well-structured, entirely generic email]
+```
+
+### Good
+
+```
+Claude: [reads the shared voice profile — empty]
+        "Before I write anything, I want to sound like you. Can I read your
+        last 20 sent emails to customers? Or paste me three you were happy with."
+```
+
+One extra step, and every draft afterward inherits it.
+
+---
+
+## Gotcha: a contact with a phone number and no email
+
+**Why it matters:** Drafting an email for a contact who has no email address produces a message that can never be sent, and inventing or pattern-guessing an address for them is how a sending domain gets flagged.
+
+### Bad
+
+```
+Owner: "Write all 12."
+Claude: [drafts 12 emails, including 3 for contacts that only have a phone number]
+```
+
+### Good
+
+```
+3 of these have a phone number and no email. I'm not drafting email for
+them. Two options:
+
+  · A call script — same opener, same reason for reaching out, built to say
+  · Send them back to lead-finder to look for an address first
+
+Which?
+```
+
+Never draft an email for a contact with no email address, and never guess one to make the batch look complete.
+
+---
+
+## Gotcha: the compliment opener
+
+**Why it matters:** "I've been following your work and I'm impressed by what you're building" is the most recognizable line in cold email. Everyone sends it, so it signals mass send in the first sentence, and nothing after it gets read.
+
+### Bad
+
+```
+I came across Ridgeline Property Group and was really impressed by the
+portfolio you've built.
+```
+
+### Good
+
+```
+Saw you filed for the Kellogg Street building. Congratulations.
+```
+
+A fact beats a compliment. It also proves someone actually looked.
+
+---
+
+## Gotcha: the empty follow-up
+
+**Why it matters:** "Just bumping this to the top of your inbox" says the sender has nothing to add but wants attention anyway. It converts poorly and it costs goodwill.
+
+### Bad
+
+```
+Subject: Re: Kellogg Street
+Hi Dana — just following up on my note below. Let me know your thoughts!
+```
+
+### Good
+
+```
+Subject: Re: Kellogg Street
+Hi Dana — one thing I should've mentioned. Corwin & Bay went from 9 separate
+contracts to 1 last year, came out 14% cheaper. Same setup as yours.
+Thanks, Ray
+```
+
+Every touch earns its place or it does not go.
+
+---
+
+## Gotcha: merge-field personalization
+
+**Why it matters:** Recipients recognize a template instantly. A message that could go to any company with two words changed is not personalized, and calling it personalized is worse than sending it plain.
+
+### Bad
+
+```
+Hi {{first_name}}, I noticed {{company}} is doing great work in the
+{{industry}} space.
+```
+
+### Good
+
+Each message opens with that company's own trigger. Twelve prospects means twelve different first lines. If one has no trigger, that message is shorter and honestly cold.
+
+---
+
+## Gotcha: sending without explicit approval
+
+**Why it matters:** Email goes out under the owner's name to real customers and prospects. There is no undo. A wrong send can cost a relationship the owner has spent years on.
+
+### Bad
+
+Queue the sequence because the owner said "yes, looks good" about message one.
+
+### Good
+
+Approval is per batch and per stage. State what will happen, wait for a yes:
+
+```
+4 messages to Dana Whitfield over 21 days, from ray@okonkwomechanical.com.
+Queue it?
+```
+
+Approving message one is not approving messages two through four.
+
+---
+
+## Gotcha: sending to inferred addresses at volume
+
+**Why it matters:** This is the most damaging failure here and the owner has no way to see it coming. Bounces at volume get the sending domain flagged. That degrades their real customer email for months, and nobody connects it back to an outreach batch from July.
+
+### Bad
+
+Send to all 12, including the 3 pattern-guessed addresses.
+
+### Good
+
+```
+⚠ 3 of 12 contacts are inferred, not verified. Recommend confirming those
+first — bounces at volume hurt your sending domain for months, including your
+customer mail.
+
+Approve all 12, or just the 9 verified?
+```
+
+Give the owner the real choice. They cannot be expected to know the risk.
+
+---
+
+## Gotcha: a follow-up landing after a reply
+
+**Why it matters:** Nothing says "automated" more clearly than a "just following up" arriving two days after the recipient already answered.
+
+### Bad
+
+Sequence runs on schedule regardless of replies.
+
+### Good
+
+Any reply stops the sequence, including out-of-office until it expires. Hand the thread to the owner.
+
+---
+
+## Gotcha: an invented result
+
+**Why it matters:** "We helped a similar company cut costs 30%" in an email the owner sends under their own name is a claim they will have to defend on the call. If it is not true, that is a real problem, not a stylistic one.
+
+### Bad
+
+```
+We've helped dozens of property managers reduce HVAC spend by up to 30%.
+```
+
+Where did 30% come from? Nowhere.
+
+### Good
+
+```
+Corwin & Bay went from 9 separate contracts to 1 last year, came out 14%
+cheaper.
+```
+
+Pull the number from actual customer data, or leave the claim out. If the owner has no comparable result to cite, say what they do instead of inventing evidence.
+
+---
+
+## Gotcha: making the same correction twice
+
+**Why it matters:** An owner who has to strike "just following up" out of every batch concludes the skill is not learning and goes back to writing by hand.
+
+### Bad
+
+Apply the edit to this draft and move on.
+
+### Good
+
+Apply it, write it into the shared voice profile, and say so:
+
+```
+Cut it, and noted it in your voice profile so it won't come back.
+```

package/content/small-business/skills/small-business-outreach-composer/reference/output_template.md

@@ -0,0 +1,147 @@
+# Output Template
+
+Present the sequence for approval before anything queues. The owner reads message one closely and skims the rest — structure the output for that.
+
+---
+
+## Structure
+
+```
+## Outreach — <who it's for>
+
+Voice: <one line on what was matched, or that a profile was just built>
+Hook:  <the specific thing this is grounded in, and its source>
+
+### Message 1 — sends immediately
+
+Subject: <subject>
+
+<full message body>
+
+### The rest of the sequence
+
+| # | Day | Subject | Angle |
+|---|---|---|---|
+| 2 | +4 | <subject> | <one line> |
+| 3 | +11 | <subject> | <one line> |
+| 4 | +21 | <subject> | <one line> |
+
+<Full text of messages 2–4 available on request — say the word.>
+
+### Before this sends
+
+<count> messages to <recipient(s)>, from <account>, over <n> days.
+<Any contact-confidence warnings.>
+
+Want changes, or should I queue it?
+```
+
+---
+
+## Worked example
+
+```
+## Outreach — Ridgeline Property Group (Dana Whitfield)
+
+Voice: Matched to your profile — short sentences, "Straight answer," "Thanks, Ray."
+Hook:  Permit filed for the Kellogg Street building, Mar 14 (county records).
+
+### Message 1 — sends immediately
+
+Subject: Kellogg Street
+
+Hi Dana,
+
+Saw you filed for the Kellogg Street building. Congratulations.
+
+Straight answer on why I'm writing: we cover six other property managers in
+the area on single service plans across all their buildings. Usually works out
+cheaper than per-building contracts.
+
+Worth 10 minutes Thursday?
+
+Thanks, Ray
+
+### The rest of the sequence
+
+| # | Day | Subject | Angle |
+|---|---|---|---|
+| 2 | +4 | Re: Kellogg Street | Corwin & Bay went from 9 contracts to 1, saved 14% |
+| 3 | +11 | Heads up on the code change | New commercial refrigerant rule, Jan deadline — useful either way |
+| 4 | +21 | Last one from me | Clean close-out, door left open |
+
+Full text of messages 2–4 available on request — say the word.
+
+### Before this sends
+
+4 messages to Dana Whitfield (dana.whitfield@ridgelinepg.com — verified),
+from ray@okonkwomechanical.com, over 21 days.
+
+Want changes, or should I queue it?
+```
+
+---
+
+## For a batch
+
+When the sequence goes to a list rather than one prospect, show one fully worked example and the personalization plan:
+
+```
+## Outreach — 12 prospects from the July list
+
+Voice: Matched to your profile.
+Structure: same 4-message sequence for all 12.
+Personalization: each message 1 opens with that company's own trigger —
+no shared opener, no merge-field templating.
+
+### Fully worked example — Ridgeline Property Group
+
+<message 1 in full>
+
+### How the other 11 open
+
+| Company | Message 1 opens with |
+|---|---|
+| Corwin & Bay | Facilities Manager posting, Apr 2 |
+| Fairmount Commercial | Second location opened in February |
+| Alder Ridge | No trigger found — honest cold intro, shorter |
+| ... | |
+
+### Before this sends
+
+48 messages to 12 contacts over 21 days, from ray@okonkwomechanical.com.
+
+⚠ 3 of 12 contacts are inferred, not verified: Corwin & Bay, Delta Park, Sunfield.
+  Recommend confirming those addresses first — bounces at volume hurt your
+  sending domain for months, including your customer mail.
+
+Approve all 12, approve the 9 verified only, or make changes?
+```
+
+**Always separate verified from inferred in the approval.** It gives the owner a real choice instead of an all-or-nothing one, and the domain-reputation risk is not something they can be expected to know about.
+
+---
+
+## Draft-only mode
+
+With no mail connector, the deliverable is copy formatted to paste. Say so without apology:
+
+```
+No mail connector, so these are drafts to paste into your own email. Send order
+and timing are noted on each — I'll track what went out if you tell me.
+```
+
+Give each message a plain header with its send day so the owner can work the sequence manually.
+
+---
+
+## After edits
+
+Fold every correction into `../../../shared/voice-profile.md`, then confirm in one line:
+
+```
+Updated. Cut "just following up" from message 2 and noted it in your voice
+profile so it won't come back.
+```
+
+That last clause is what makes the skill feel like it is learning rather than being re-corrected every week.

package/content/small-business/skills/small-business-outreach-composer/reference/sequence_patterns.md

@@ -0,0 +1,99 @@
+# Sequence Patterns
+
+Structure and cadence by scenario. The rule underneath all of them: every message adds something new. A touch whose only content is "checking in" teaches the recipient to ignore the sender.
+
+---
+
+## Cold outreach — 4 messages, 3 weeks
+
+| # | Day | Angle | Ceiling |
+|---|---|---|---|
+| 1 | 0 | The trigger. Why them, why now, one small ask | 120 words |
+| 2 | +4 | A comparable result — a similar customer, a specific number | 60 words |
+| 3 | +11 | Something genuinely useful, asking nothing | 80 words |
+| 4 | +21 | Clean close-out. Say you'll stop, leave the door open | 40 words |
+
+Message 3 is the one most owners skip and the one that most often works. Send something the prospect can use whether or not they ever buy — a relevant code change, a seasonal warning, a benchmark. It is the only message in the sequence that isn't asking for something, which is exactly why it gets read.
+
+Message 4 matters too. A clean "I'll leave it here, reach out anytime" gets more replies than any of the middle touches, because it removes the pressure.
+
+---
+
+## Warm or referral — 3 messages, 2 weeks
+
+| # | Day | Angle | Ceiling |
+|---|---|---|---|
+| 1 | 0 | Lead with the connection by name. Ask directly | 150 words |
+| 2 | +5 | Add the specific relevance to their situation | 70 words |
+| 3 | +14 | Close out, and mention you'll tell the referrer you tried | 50 words |
+
+**Name the referrer in the first line.** Burying it in paragraph two wastes the only real advantage this sequence has.
+
+Confirm the referrer is happy to be named before sending. Using someone's name without asking can cost the owner a relationship worth more than the deal.
+
+---
+
+## Post-meeting follow-up — 2 messages, 10 days
+
+| # | Day | Angle | Ceiling |
+|---|---|---|---|
+| 1 | 0 (same day) | What was agreed, what happens next, who does what | 100 words |
+| 2 | +7 | The specific next step, if nothing has moved | 50 words |
+
+Same-day matters more than polish here. A short accurate recap sent within hours beats a careful one sent Monday.
+
+If a proposal was promised, this sequence hands off to `proposal-builder` rather than trying to cover it.
+
+---
+
+## Re-engagement of a quiet customer — 3 messages, 4 weeks
+
+| # | Day | Angle | Ceiling |
+|---|---|---|---|
+| 1 | 0 | Acknowledge the gap honestly. No pitch | 90 words |
+| 2 | +10 | What has changed since — new service, new hours, new capability | 80 words |
+| 3 | +28 | A specific, time-bound reason to come back | 70 words |
+
+The first message must not sell. A customer who went quiet often did so for a reason, and a pitch confirms they were right to. Ask what happened, and mean it.
+
+If they answer with a complaint, stop the sequence and hand to `review-reputation` or `ticket-deflector`. Continuing to sell over a complaint is how a quiet customer becomes a public review.
+
+---
+
+## Universal rules
+
+**Stop the sequence on any reply.** Including an out-of-office, until it expires. A follow-up landing after someone already answered is the clearest possible sign of automation.
+
+**Never send two messages in the same 48 hours.**
+
+**Match the prospect's medium.** If they replied by text, the follow-up is a text.
+
+**Vary the subject lines.** Four messages with the same subject stack into one thread that reads as nagging. Each subject should reflect that message's angle.
+
+**Ceilings are ceilings, not targets.** A 40-word message that says the thing outperforms a 118-word one that circles it.
+
+---
+
+## Sending windows
+
+Send when the recipient reads, not when it is convenient to queue.
+
+| Audience | Best window |
+|---|---|
+| Trades and field services | 6–8 am, or after 5 pm |
+| Office and professional services | 8–10 am Tue–Thu |
+| Retail and hospitality | Mid-morning, avoid weekends entirely |
+| Healthcare practices | Early morning before clinic opens |
+
+Avoid Monday morning and Friday afternoon for everything. Neither gets read.
+
+---
+
+## When to stop entirely
+
+- They replied — stop, and hand to the owner
+- They asked to be removed — stop permanently and record it
+- The email hard-bounced — stop, and mark the contact bad so no other skill retries it
+- Four touches with no engagement — stop. A fifth does not convert, it just annoys
+
+Record every stop reason. The next run needs to know, and contacting someone the owner already burned is worse than not contacting them at all.