opencode-knowledge-work 0.0.0-stage → 0.1.1

package/content/small-business/skills/small-business-lead-finder/reference/output_template.md

@@ -0,0 +1,124 @@
+# Output Template
+
+Chat summary first, XLSX second, CRM write only after approval.
+
+---
+
+## Chat summary
+
+```
+## Prospect list — <count> companies
+
+<One sentence on what the profile turned out to be.>
+
+### Start with these
+
+1. **<Company>** — <size, location> · <the signal, with date and source>
+   <Contact name, title, how to reach them>
+2. ...
+
+<Through 10.>
+
+### About this list
+
+Built from <n> of your customers. Profile: <one line>.
+Sourced via <Apollo | web research>. <count> companies met the bar; <n> more
+were found and cut for weak fit.
+
+<Full list attached as XLSX with all columns.>
+```
+
+Ten in chat is the right number. It is what an owner will actually read before deciding whether the list is any good.
+
+---
+
+## Worked example
+
+```
+## Prospect list — 47 companies
+
+Your best customers are commercial property managers with 3 to 15 buildings
+inside 25 miles who came in through referrals — not the residential emergency
+calls that make up most of your volume.
+
+### Start with these
+
+1. **Ridgeline Property Group** — 6 buildings, 18 mi · Filed a permit for a 7th
+   on Mar 14 (county records). Current HVAC vendor has three 2-star reviews
+   this quarter.
+   Dana Whitfield, Facilities Director · direct line verified
+
+2. **Corwin & Bay Management** — 9 buildings, 11 mi · Hired a Facilities
+   Manager, posted Apr 2. Shares a tenant with your customer Alder Street
+   Partners — possible warm intro.
+   Marcus Ilo, Operations Director · email inferred, not verified
+
+3. **Fairmount Commercial** — 4 buildings, 23 mi · Opened their second
+   location in February.
+   Contact unknown — general office line only
+
+### About this list
+
+Built from 340 of your customers. Profile: commercial property managers,
+3–15 buildings, within 25 miles, referral-sourced, maintenance contract first.
+Sourced via web research (Apollo not connected) — county permit filings,
+property association roster, and review platforms.
+47 companies met the bar; 61 more were found and cut for weak fit.
+
+Full list attached as XLSX.
+```
+
+Note row 3. Contact unknown, kept anyway, marked honestly. The owner may already know them.
+
+---
+
+## XLSX columns
+
+In this order. The first six are what gets used; the rest is evidence.
+
+| Column | Notes |
+|---|---|
+| Rank | 1 to n |
+| Company | |
+| Why now | The signal, in one sentence, with its date |
+| Contact | Name and title, or "unknown" |
+| Contact route | Email, phone, or the path to find one |
+| Contact confidence | verified · inferred · unknown |
+| Fit score | 0–10 |
+| Signal score | 0–10 |
+| Reachability score | 0–10 |
+| Total score | |
+| Size | Employees, locations, or revenue band |
+| Location | City and distance from the owner |
+| Signal source | Where the trigger came from, with a link where one exists |
+| Warm path | Shared customer or connection, if any |
+| Notes | Anything that didn't fit above |
+
+Freeze the header row. Sort by total score descending. Format scores as numbers, not text.
+
+---
+
+## The CRM write
+
+Only after an explicit yes, and only after saying exactly what will happen:
+
+```
+Ready to add to HubSpot: 47 companies and 39 contacts, tagged
+"prospect-list-2026-07". Nothing existing gets modified. Say go and I'll create them.
+```
+
+Name the tag. Confirm nothing existing is touched. A bad bulk import takes hours to unwind, and the owner has no way to preview it themselves.
+
+If they decline, the XLSX is the deliverable. That is a complete outcome, not a partial one.
+
+---
+
+## Contact confidence is not optional
+
+Every contact row carries its confidence level.
+
+- **verified** — the address or number came from a source that confirms it
+- **inferred** — constructed from a pattern, such as a standard email format
+- **unknown** — no route found
+
+Sending to inferred addresses at volume is how a domain gets flagged as spam. That damage lasts months and it hits the owner's real customer email too. Mark it so the outreach step can treat it differently.

package/content/small-business/skills/small-business-lead-finder/reference/scoring.md

@@ -0,0 +1,92 @@
+# Scoring
+
+Three components. The score decides the order the owner works the list in, which is the main thing the list is for.
+
+```
+score = (fit x 0.4) + (signal x 0.4) + (reachability x 0.2)
+```
+
+Each component runs 0 to 10. Signal is weighted equal to fit deliberately — a good-fit company with nothing happening is a cold call, and cold calls are what the owner was already doing badly.
+
+---
+
+## Fit — 40%
+
+How closely the company matches the profile from `icp_method.md`.
+
+| Score | Meaning |
+|---|---|
+| 9–10 | Matches every profile criterion |
+| 7–8 | Matches the core criteria, off on one secondary dimension |
+| 5–6 | Plausible, but missing something that matters |
+| 3–4 | Adjacent — worth including only if signal is strong |
+| 0–2 | Do not include it |
+
+If the profile has a counter-pattern ("under 10 employees churns"), a company matching the counter-pattern caps at 4 regardless of everything else.
+
+---
+
+## Signal — 40%
+
+Evidence something is happening right now. This is the difference between a prospect list and a directory.
+
+| Signal | Score | Why it matters |
+|---|---|---|
+| New location, expansion, or major permit filed | 10 | They are spending and their existing vendors may not scale |
+| Hiring for a role related to what the owner sells | 9 | Budget already approved |
+| Leadership or ownership change | 8 | New decision-makers re-evaluate vendors |
+| Funding, acquisition, or major contract won | 8 | Money and new needs at once |
+| Recent poor reviews of their current provider | 8 | Active dissatisfaction, usually the warmest signal available |
+| Seasonal timing matches their buying cycle | 6 | Right time, no specific trigger |
+| Recent website or brand refresh | 5 | Investing, but weak evidence of need |
+| Nothing found | 2 | Not disqualifying, just cold |
+
+**A signal needs a date and a source.** "Expanding" is a rumor. "Filed a permit for a second location on Mar 14, county records" is a reason to call this week.
+
+Never invent a signal. A prospect list with fabricated triggers destroys the owner's credibility on the first call, and they will never trust the skill again.
+
+---
+
+## Reachability — 20%
+
+How directly the owner can get in front of the decision-maker.
+
+| Route | Score |
+|---|---|
+| Shared customer or mutual connection who would introduce | 10 |
+| Named decision-maker with a verified direct contact | 8 |
+| Named decision-maker, contact inferred but unverified | 6 |
+| Named person, but not the decision-maker | 4 |
+| General company contact only | 3 |
+| No contact route found | 1 |
+
+**Warm paths are worth hunting for.** Cross-check target companies against the owner's existing customer list, shared associations, and overlapping geography. A referral route converts several times better than anything cold, and owners consistently underestimate how many they already have.
+
+---
+
+## Presenting the score
+
+Show the rank and the reason, not the arithmetic. Owners do not want to see a weighted formula; they want to know why this company is number three.
+
+**Bad:**
+```
+Ridgeline Property Group — score 8.4
+```
+
+**Good:**
+```
+3. Ridgeline Property Group — 6 buildings, 18 miles out.
+   Filed a permit for a 7th on Mar 14. Their current HVAC vendor has
+   three 2-star reviews this quarter. Contact: Dana Whitfield, Facilities
+   Director, direct line verified.
+```
+
+Same score. Only one of them gets called.
+
+---
+
+## Ties and cutoffs
+
+Break ties toward signal recency. A trigger from last week beats one from last quarter.
+
+Anything scoring below 4 does not go on the list at all. Including weak rows to reach a target count is the fastest way to make the ranking meaningless, and the ranking is the product.

package/content/small-business/skills/small-business-lead-finder/reference/sourcing.md

@@ -0,0 +1,78 @@
+# Sourcing Look-alikes
+
+Two paths. Apollo when it's connected, web research when it isn't. Both produce a real list.
+
+---
+
+## With Apollo
+
+The primary path. Filter on the profile dimensions, then pull contacts and signals in the same pass.
+
+Useful filters, in rough order of value for this segment:
+
+- Industry and sub-industry
+- Employee count band
+- Location radius from the owner
+- Technologies in use, where it indicates fit
+- Recent hiring activity
+- Funding or ownership change
+
+Pull contacts by title rather than by name. For SMB targets the decision-maker titles worth searching are owner, president, general manager, operations manager, and facilities manager. Titles vary enormously by trade — check what the owner's existing contacts are called and search for those.
+
+**Clay** is a peer of Apollo (`../../../shared/connector-neutrality.md`): whichever is connected runs the search. Same approach, different tool — `find-and-enrich-company` for the look-alike companies, `find-and-enrich-contacts-at-company` for the people. Both are metered; name the estimated credits before searching.
+
+---
+
+## Without Apollo — web research
+
+Slower, smaller, and often higher quality per row because each company was actually looked at. Do not treat this as degraded output.
+
+### General sources
+
+- Industry association member directories — usually the single best source
+- State and county business registries and license lookups
+- Chamber of commerce member lists
+- Review platforms, filtered by category and geography
+- LinkedIn company search
+- Local news for expansions, openings, and awards
+
+### By industry
+
+| Industry | Where the list lives |
+|---|---|
+| Trades and construction | Contractor license databases, permit filings, builder association rosters |
+| Healthcare | State provider directories, practice association lists, facility licensing records |
+| Restaurants and retail | Health inspection databases, delivery platform listings, mall and district directories |
+| Professional services | Bar and CPA association directories, industry award lists |
+| Manufacturing | Supplier directories, trade show exhibitor lists, industry registries |
+| Nonprofits | Grantmaker databases, state charity registries, foundation 990 filings |
+| Property management | Property records, apartment association rosters, listing sites |
+
+**Permit and license filings are the most underrated source for trades.** They are public, dated, and a filing is itself a buying signal.
+
+### Contact discovery without a data provider
+
+- Company website team and about pages
+- Public filings that name officers
+- Association member listings, which often include a named contact
+- Review responses, which are frequently signed by the owner
+
+When a contact cannot be found, keep the company and mark the contact unknown. Do not drop a good-fit company because the name is missing — the owner may already know them.
+
+---
+
+## How many rows
+
+Target 40 to 60 companies.
+
+A five-hundred-row scrape looks impressive and gets ignored, because the owner cannot tell which twenty to start with and the effort of finding out exceeds the effort of the original manual process. Forty researched rows with a reason attached each get worked.
+
+If the profile is genuinely narrow and only 12 companies exist, deliver 12 and say so. A short honest list is fine. Padding it with poor fits to hit a number destroys the ranking, which is the entire value of the deliverable.
+
+---
+
+## Verification
+
+Before a row goes on the list, confirm the company still exists and still matches. Directories go stale, businesses close, and a list with dead companies on it gets abandoned after the third bounce.
+
+Check the website resolves and the business looks active. This is quick and it is the difference between a list that gets worked and one that gets deleted.

package/content/small-business/skills/small-business-lead-triage/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: lead-triage
+version: 0.1.1
+description: >
+  Scores inbound HubSpot leads by engagement signals, company fit, and urgency
+  markers, ranks the ones worth a call today with talking points, drafts the
+  follow-ups, and proposes calendar times for the owner to book. Use when the
+  owner asks to prioritize, score, or rank leads, asks "who should I call
+  first," or asks about their pipeline. An ask that wants the ranked leads
+  turned into a call list with time blocked on the calendar routes to
+  /call-list, which runs this skill first and then books the time.
+allowed-tools: Read, WebFetch
+---
+
+# Lead Triage
+
+## Quick start
+
+Pull inbound leads from HubSpot, score them, and surface a ranked call list with talking points. Drafts follow-ups and proposes calendar slots — never sends or books without owner approval.
+
+```
+User: "prioritize my leads"
+→ Pull contacts: lifecycle stage Lead or MQL, status ≠ Unqualified
+→ Score each across engagement, company fit, urgency, recency
+→ Return ranked list (size adapts to volume) with talking points
+→ Offer to draft follow-ups and propose calendar slots
+```
+
+## Workflow
+
+1. **Pull leads from HubSpot.** Fetch contacts with `lifecyclestage` = `Lead` or `MQL` and `hs_lead_status` ≠ `Unqualified`. Use the field list in [reference/hubspot-scoring.md](reference/hubspot-scoring.md). If HubSpot is unavailable — not installed, not connected, or erroring — do not stop. Say so plainly and run the "No HubSpot?" path at the bottom of this file: ask for a CSV export or a rough pasted list, and score that instead.
+   - **Empty portal check.** If the pull returns zero contacts of any lifecycle stage, the portal is empty, not filtered wrong. Say so in one line, offer HubSpot's own setup (`manage_onboarding`, action `SET_GOAL`) or the "No HubSpot?" path, and do not diagnose lifecycle stages on a portal with nothing in it. The count is the test: `get_user_details` returns an `onboarded` flag, but a portal can report `onboarded: false` while holding hundreds of contacts, so the flag alone never decides this.
+
+2. **Clarify if trigger is ambiguous.** If the user said only "pipeline" without a qualifier, ask: *"Quick pipeline overview (deal stages + total value) or prioritized call list?"* — then route accordingly. Do not score leads on a bare "pipeline."
+
+3. **Score each lead.** Apply the four-dimension model in [reference/hubspot-scoring.md](reference/hubspot-scoring.md):
+   - **Engagement** — email replies, opens, site visits in HubSpot (last 30 days only)
+   - **Company fit** — industry and employee count vs. owner's ICP (default: any industry, 1–50 employees). Read these from the company associated with the lead, not from the contact record — see the scoring reference. When leads have no associated company and a lead-data connector (Apollo or Clay) is connected, the enrichment leg in the scoring reference fills industry and size from the lead's email domain. It is metered — say how many rows it would enrich and what that costs in credits, and run it only on the owner's yes for this run. Nothing enriched is written back to the CRM from here.
+   - **Urgency** — lead age, stage duration, notes containing "urgent / ASAP / deadline / budget approved". The keyword check requires actually fetching note bodies via the contact → notes association — follow the "Fetch note bodies" section of the scoring reference; the note count alone cannot fire it.
+   - **Recency penalty** — subtract points if last activity was <24 hours ago (already touched today)
+
+   **Then check whether the scores actually separated.** If the highest and lowest composite differ by less than 10 points, the CRM has no signal to rank on. Do not present the order as a ranking — run the flat-score path in the scoring reference, say plainly that the signals are empty, and order by CRM facts instead. A false ranking sends the owner to call the wrong person.
+
+4. **Build the ranked list.** Sort descending by composite score. Adapt list size to volume:
+   - ≤10 leads → show all
+   - 11–30 leads → show top 5
+   - >30 leads → show top 8
+
+   For each lead: name, company, score, one-paragraph talking point, last activity summary. If engagement signals are all >30 days old, flag: *"Engagement signals are stale — approach as cold outreach."*
+
+5. **Offer follow-up drafts.** Ask: *"Draft follow-ups for any of these?"* If yes, write one email per selected lead in the owner's voice per [the shared voice profile](../../shared/voice-profile.md). If that file has no profile yet, follow its "When there is no sample" instruction — ask for three emails the owner was happy with; if they decline, draft plain and neutral and say the drafts are un-voiced. Never invent a personality. Show drafts; do not send. If Mail is unavailable, hand the drafts over in chat as subject plus body for the owner to paste — that is a complete outcome.
+
+6. **Render the triage board as an artifact.** After the short chat answer — never instead of it — build an HTML page using the house artifact style (`../../shared/artifact-style.md`): a ranked table with each lead's composite score in mono, an urgency status pill per row (good / warn / critical), and a talking-points line under each lead. If the flat-score path fired, say so on the page and drop the pill colors to neutral.
+
+7. **Offer calendar slots.** Ask: *"Propose call slots for any of these?"* If yes, check Calendar for open 30-minute windows in the next two business days (avoid slots with existing events ±15 min). Propose two options per lead. Never create calendar events without explicit owner approval. If Calendar is unavailable, ask the owner for two or three windows they can offer and use those instead of inventing times.
+
+## Approval gates
+
+- **Never send an email.** Draft only; owner sends from their inbox.
+- **Never create calendar events until approved by the user.**
+- **Never change lifecycle stage or mark a lead Unqualified** unless the owner explicitly asks.
+- **Never include `Customer` or `Evangelist` lifecycle contacts** in the lead list.
+- **If zero leads match the filter**, explain why and offer to check what lifecycle stages are in use — do not fabricate a list.
+
+## Reference
+
+- [reference/hubspot-scoring.md](reference/hubspot-scoring.md) — HubSpot field names, scoring weights, ICP defaults
+- [reference/gotchas.md](reference/gotchas.md) — edge cases: stale data, zero leads, pipeline disambiguation, customer contamination
+- [reference/examples/happy-path-triage.md](reference/examples/happy-path-triage.md) — worked output for a 7-lead list with draft and slot proposal
+
+## Closing offer
+
+End with one line on what the triage produced, then the most relevant next step with its trigger phrase — usually "call list" (`/call-list`) to add calendar blocks around the ranking. Up to two others when they fit: "write this outreach" (`outreach-composer`) or "update the CRM" (`crm-autopilot`). Never more than three, and never re-offer something the owner already declined this session.
+
+## No HubSpot?
+
+Paste or upload the lead list — a CSV export or even a rough list works. Scoring and talking points run the same; the ranked call list comes back as chat plus a file instead of writing to the CRM.
+
+## 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-lead-triage/reference/examples/happy-path-triage.md

@@ -0,0 +1,68 @@
+# Example: Happy-path triage — 7-lead list
+
+7 leads → show all (≤10 rule). Owner ICP: SaaS, 10–50 employees.
+
+---
+
+## Ranked output
+
+```
+Here are your 7 leads, ranked by priority:
+
+─────────────────────────────────────
+1. Sarah Chen · Acme SaaS · Score: 78
+   Last activity: 2 days ago (email reply)
+   Sarah replied asking about API limits — evaluating for a 22-person team.
+   Strong ICP fit. Lead is 12 days old (prime window). Open with her API
+   question; offer a 20-min demo to walk through limits live.
+
+2. Marcus Webb · Loop Analytics · Score: 64
+   Last activity: 5 days ago (site visit)
+   Visited pricing page twice this week, no reply to outreach. 31 employees,
+   SaaS — good fit. Try a softer touch: share a case study instead of another
+   demo ask.
+
+3. Priya Nair · BuildFast · Score: 51
+   Last activity: 9 days ago (email open)
+   Opened the intro email, no reply. 18 days old — approaching stale. One
+   more value-add touch (ROI one-pager) before deprioritizing.
+
+[4–7 follow same format, scores 30–45]
+─────────────────────────────────────
+
+Draft follow-ups for any of these? (e.g., "draft for 1 and 2")
+Propose call slots? (e.g., "find times for Sarah and Marcus")
+```
+
+---
+
+## Follow-up draft — Sarah Chen
+
+```
+Subject: Re: API limits question
+
+Hi Sarah,
+
+Happy to answer the API limits question properly on a short call rather
+than over email.
+
+[Owner adds availability after booking]
+
+Would that work?
+
+[Owner name]
+```
+Draft shown. Not sent.
+
+---
+
+## Calendar proposal — Sarah Chen
+
+```
+Open 30-min slots (next 2 business days):
+  • Thu Apr 25 · 10:00–10:30 AM
+  • Thu Apr 25 · 2:00–2:30 PM
+  • Fri Apr 26 · 9:00–9:30 AM
+
+No events created — pick one and book it directly.
+```

package/content/small-business/skills/small-business-lead-triage/reference/gotchas.md

@@ -0,0 +1,76 @@
+# Gotchas — lead-triage
+
+---
+
+## Gotcha: "Pipeline" bare trigger runs full scoring when user just wants a status check
+
+**Why it matters:** "Pipeline" alone is ambiguous — the owner may want deal-stage totals, not a scored call list.
+
+### ✗ Bad
+```
+User: "how's my pipeline?"
+Claude: [runs full scoring, returns 12-lead ranked list]
+```
+
+### ✓ Good
+```
+User: "how's my pipeline?"
+Claude: "Quick pipeline overview (deal stages + total value) or prioritized
+         call list for today?"
+```
+
+---
+
+## Gotcha: Stale engagement data inflates scores
+
+**Why it matters:** `hs_email_open` is cumulative — opens from a year-old campaign make a cold lead look hot.
+
+### ✗ Bad
+```
+Lead has 20 opens (all 11 months ago). Scores 25/25 on engagement.
+Appears as #1. Owner calls; lead has no memory of the brand.
+```
+
+### ✓ Good
+```
+Cap engagement signals at 30 days. If all signals are older than 30 days,
+engagement score = 0 and talking point notes:
+"Engagement signals are stale (last: [date]) — approach as cold outreach."
+```
+
+---
+
+## Gotcha: Customers appear in the lead list
+
+**Why it matters:** Calling a `Customer` or `Evangelist` as a lead prospect is embarrassing.
+
+### ✗ Bad
+```
+Lifecycle filter not applied → existing customer appears as #2 on the list.
+```
+
+### ✓ Good
+```
+Filter strictly: lifecyclestage = Lead or MQL only.
+If a contact has a blank lifecycle stage, include with a warning flag:
+"⚠ Lifecycle stage not set — confirm this is a lead before calling."
+```
+
+---
+
+## Gotcha: Proposing calendar slots that conflict with existing events
+
+**Why it matters:** Proposing a time the owner is already booked erodes trust immediately.
+
+### ✗ Bad
+```
+Claude proposes "Tuesday 2–2:30 PM" without checking Calendar.
+Owner already has a client call in that slot.
+```
+
+### ✓ Good
+```
+Fetch Calendar for next two business days before proposing any slot.
+Only propose windows with no existing events ±15 minutes buffer.
+If no free window exists, say so and offer to look further out.
+```