opencode-knowledge-work 0.0.0-stage → 0.1.1

package/content/small-business/skills/small-business-business-pulse/reference/gotchas.md

@@ -0,0 +1,103 @@
+# Gotchas
+
+Known failure modes for the business-pulse skill. Good / Bad pairs.
+
+---
+
+## Gotcha: QuickBooks returns unexpected state
+
+**Why it matters:** QuickBooks can return empty results, a sync-in-progress state, or an auth error without throwing a hard exception. Treating silence as "no data" causes the pulse to skip Cash entirely without telling the owner — they assume their business has no QuickBooks data.
+
+### ✗ Bad
+
+```
+Claude: [QuickBooks returns empty response]
+        → skips Cash section silently
+        → pulse presents no cash data; owner assumes QB isn't connected
+```
+
+The owner spends 10 minutes reconnecting QuickBooks before realizing it was always connected — just in a transient state.
+
+### ✓ Good
+
+```
+Claude: [QuickBooks returns empty response or error]
+        → Cash section header present with: "n/a — QuickBooks unavailable (sync error or auth required)"
+        → "Sources unavailable: QuickBooks — returned empty response" in appendix
+```
+
+The owner sees the gap explicitly and can decide whether to reconnect or proceed with a partial pulse.
+
+---
+
+## Gotcha: Gmail auth failure mid-pulse
+
+**Why it matters:** Gmail auth is intermittently flaky. Surfacing a raw auth error in the middle of the pulse looks broken and breaks the owner's trust in the skill.
+
+### ✗ Bad
+
+```
+Claude: [Gmail auth error mid-composition]
+        → "Error: Gmail authentication failed. Please re-authenticate."
+        → pulse output stops or shows raw error in Watch List section
+```
+
+The owner sees a broken tool, not a useful briefing.
+
+### ✓ Good
+
+```
+Claude: [Gmail auth error]
+        → continues pulse without Watch List section
+        → appendix: "Gmail — auth error; Watch List unavailable this run"
+        → all other sections unaffected
+```
+
+The pulse still delivers value. The owner is informed, not alarmed.
+
+---
+
+## Gotcha: Asking permission before pulling data
+
+**Why it matters:** The skill's core value is doing the work without prompting. An owner who invoked the pulse already implicitly approved the data pull. Asking "should I check QuickBooks?" or "can I read your emails?" defeats the purpose and erodes trust in the skill as an autonomous assistant.
+
+### ✗ Bad
+
+```
+Owner: "catch me up on the business"
+Claude: "Should I check QuickBooks for your cash balance? And is it okay to look at your HubSpot pipeline?"
+```
+
+Three more round trips before anything useful is delivered.
+
+### ✓ Good
+
+```
+Owner: "catch me up on the business"
+Claude: [immediately dispatches all parallel tool calls]
+        → presents pulse in one response
+```
+
+---
+
+## Gotcha: Slack write requires explicit confirmation
+
+**Why it matters:** Slack write posts to channels other people can see. Auto-posting without confirmation could embarrass the owner or spam a team.
+
+### ✗ Bad
+
+```
+Claude: [at end of pulse]
+        "I've posted this to #general."
+```
+
+Owner never asked for a Slack post; now the whole team has the financial data.
+
+### ✓ Good
+
+```
+Claude: [at end of pulse]
+        "Want me to post this to Slack? If so, which channel?"
+```
+
+Slack write only happens with a specific "yes + channel name" from the owner. Never assume.

package/content/small-business/skills/small-business-business-pulse/reference/output_template.md

@@ -0,0 +1,109 @@
+# Output Template
+
+This is the exact structure every pulse must follow. Do not reorder sections. Omit a section only if its connector returned no data — never leave an empty header.
+
+Variables in `{{double braces}}` are placeholders — replace with computed values. Arrow convention: ▲ up, ▼ down, ▬ flat (<1% change). Always show the delta value after the arrow.
+
+`{{CCY}}` is the business's ISO currency code from the `## Business context` block (`../../../shared/currency-and-locale.md`) — `AUD`, `GBP`, `USD`. Never emit a bare `$`.
+
+---
+
+```markdown
+# Business Pulse — {{Day, Month Date, Year}}
+
+**Overall: {{🟢|🟡|🔴}} {{one-line status, e.g. "Cash healthy, one overdue invoice needs attention."}}}**
+
+## TL;DR
+
+- {{Most important number-backed fact, e.g. "Cash balance USD 84k, down USD 6k WoW — two large vendor payments cleared."}}
+- {{Second most important, e.g. "USD 3,400 from Acme Corp is 47 days overdue — no response since Mar 12."}}
+- {{Third, e.g. "Pipeline USD 128k weighted; two deals gone cold this week."}}
+
+---
+
+## 💰 Cash & Finance — {{🟢|🟡|🔴}}
+
+- **Cash balance**: {{CCY}} {{BALANCE}} ({{▲|▼|▬}} {{CCY}} {{DELTA}} WoW)
+- **MTD revenue**: {{CCY}} {{MTD}} vs. {{CCY}} {{PRIOR_MTD}} last month ({{▲|▼|▬}} {{PCT}}%)
+- **Outstanding AR**: {{CCY}} {{AR_TOTAL}} across {{N}} open invoices
+
+**AR aging**
+- 0–30 days: {{CCY}} {{AR_0_30}}
+- 31–60 days: {{CCY}} {{AR_31_60}} {{🟡 if nonzero}}
+- 61+ days: {{CCY}} {{AR_61}} {{🔴 if nonzero}}
+
+**Overdue > 30 days**
+- {{customer}} — {{CCY}} {{amount}} ({{days}} days overdue)
+- {{customer}} — {{CCY}} {{amount}} ({{days}} days)
+
+---
+
+## 📈 Revenue & Sales — {{🟢|🟡|🔴}}
+
+- **7-day settlements**: {{CCY}} {{SETTLEMENTS}} ({{▲|▼|▬}} {{PCT}}% vs. prior 7 days)
+- **PayPal**: {{CCY}} {{PAYPAL_TOTAL}} | **Square**: {{CCY}} {{SQUARE_TOTAL}} {{omit if not connected}}
+
+**Unusual transactions**
+- {{amount}} — {{counterparty}} — {{status: failed/pending/large}}
+- {{or "No unusual transactions this week."}}
+
+---
+
+## 🔮 Pipeline — {{🟢|🟡|🔴}}
+
+- **Weighted pipeline**: {{CCY}} {{WEIGHTED}} ({{▲|▼|▬}} {{CCY}} {{DELTA}} WoW)
+- **Coverage vs. target**: {{RATIO}}x monthly target {{🟢|🟡|🔴}}
+- **Closed-won this week**: {{CCY}} {{CW}} across {{N}} deals
+- **New deals created**: {{N}} ({{CCY}} {{TOTAL}})
+
+**Deals needing attention**
+- {{deal name}} — {{stage}} — {{why: gone cold / slipped / stalled}}
+- {{or "No deals flagged this week."}}
+
+---
+
+## 📅 This Week
+
+- {{Meeting/deadline — external party, why it matters}}
+- {{Meeting/deadline}}
+- {{Meeting/deadline}}
+{{3–5 items max. Omit internal-only calendar noise.}}
+
+---
+
+## ✉️ Watch List
+
+- {{sender / source}} — {{one-line summary of what needs attention}}
+- {{sender / source}} — {{summary}}
+{{Or: "No urgent threads detected." — include this explicitly so the owner knows the check ran.}}
+
+---
+
+## ⚠️ #1 Priority
+
+{{One specific thing to act on today. Name amounts, people, deadlines.
+Not "review cash flow" — say "The USD 4,200 invoice from Acme Corp is 23 days
+overdue. Call Sarah Chen at 415-555-0192 today."}}
+
+---
+
+## Appendix
+
+**Window**: {{date range}}
+
+**Sources pulled**: {{list of connectors that returned data}}
+
+**Sources unavailable**: {{list with reason, e.g. "Gmail — auth error" or "Zoho Desk — not connected"}}
+
+**Thresholds used**: {{note any TODO thresholds that are still defaults}}
+```
+
+---
+
+## Formatting rules
+
+1. **Amounts**: the business's currency code, then the figure — `AUD 43k` for thousands, `GBP 1.2m` for millions. No unnecessary decimals, never a bare symbol.
+2. **Percentages**: one decimal for trends (e.g. "▲ 8.3%"), integers elsewhere.
+3. **Dates**: human-readable in prose, in the owner's country convention ("14 Apr" for most countries, "Apr 14" for the US — `../../../shared/currency-and-locale.md`); ISO in metadata ("2026-04-14").
+4. **Arrow spacing**: `▲ USD 2k` not `▲USD 2k`.
+5. **Length**: aim for one page. Two pages max. If a section balloons, tighten prose.

package/content/small-business/skills/small-business-business-pulse/reference/thresholds.md

@@ -0,0 +1,71 @@
+# Thresholds
+
+Red/yellow/green cutoffs for each section of the pulse. These are SMB defaults — edit them to match the owner's actual targets and plan.
+
+Any threshold marked `# TODO: confirm with owner` should produce a note at the top of the first pulse output so the owner knows to tune it.
+
+Amount thresholds are in the business's own currency (`../../../shared/currency-and-locale.md`): "200" means 200 of whatever the business invoices in. They are attention lines, not legal ones, and do not need converting.
+
+---
+
+## Cash & Finance
+
+**Cash runway**
+- 🟢 ≥ 6 months  # TODO: confirm with owner
+- 🟡 3–6 months
+- 🔴 < 3 months
+
+**Revenue trend (MoM)**
+- 🟢 ≥ 0% (flat or growing)
+- 🟡 -5% to 0%
+- 🔴 < -5%
+
+**AR aging**
+- 🟢 No invoices past 31 days
+- 🟡 Any invoice 31–60 days past due
+- 🔴 Any invoice 60+ days past due OR total 61+ bucket > 10% of AR
+
+**Overdue threshold**: any single invoice past due > 30 days gets named explicitly in the pulse — not just counted.
+
+---
+
+## Revenue & Sales
+
+**7-day sales trend (vs. prior 7 days)**
+- 🟢 ≥ 0%
+- 🟡 -10% to 0%
+- 🔴 < -10%
+
+**Failed transactions**
+- 🟡 Any failed transaction > 200
+- 🔴 Any failed transaction > 1,000, or 3+ failures in the week
+
+---
+
+## Pipeline
+
+**Pipeline coverage** (weighted pipeline ÷ monthly revenue target)  # TODO: confirm target with owner
+- 🟢 ≥ 2x monthly target
+- 🟡 1–2x
+- 🔴 < 1x
+
+**Stale deal**: no activity in 7+ days → flag  # TODO: owner may prefer 14 days
+**Slipped deal**: open deal with close date in past → always flag
+
+---
+
+## Watch List
+
+No numeric thresholds — any escalation or complaint in mail or Slack gets surfaced. Severity is contextual; surface and let the owner decide.
+
+---
+
+## Overall status rollup
+
+The pulse-level overall status is the worst section status. Override: if any individual risk names a specific customer with a dollar amount and a deadline within 7 days, roll up to 🔴 regardless of section colors.
+
+---
+
+## When to tune
+
+Revisit these after 4 weeks of use. The defaults are conservative starting points — a healthy business will feel like it's always 🟢. Tighten them to reflect where the owner actually wants to act.

package/content/small-business/skills/small-business-business-pulse/reference/v2_sources.md

@@ -0,0 +1,63 @@
+# More sources
+
+Two more legs into the same pulse. The pulse still builds from whatever is connected and degrades gracefully.
+
+---
+
+## Shopify
+
+For a commerce business this is the difference between a pulse that describes their day and one that doesn't.
+
+| Pull | Section it feeds |
+|---|---|
+| Orders and revenue, today and trailing 7 days | Revenue & Sales |
+| Fulfillment status | Watch List — unfulfilled past SLA is the most actionable thing in the pulse |
+| Refunds and returns | Watch List |
+| Low-stock alerts on moving products | Watch List |
+
+Unfulfilled orders past their promised window belong near the top. They are time-sensitive, they turn into complaints, and no other section surfaces them.
+
+---
+
+## The ledger — MYOB, NetSuite, QuickBooks, Xero, or Zoho Books
+
+Whichever is connected is the system of record for cash, revenue, and AR, and the pulse reports the number the owner's bookkeeper or controller sees. Ledgers are peers (`../../../shared/connector-neutrality.md`): none takes precedence over another. Same metrics, same sections; only the tool names change (`data_sources.md`).
+
+**Two ledgers connected: read both, total from one.** Ask which is the source of record, say which in the Appendix, and take cash, revenue, and AR totals from that one. The other supplies only what it uniquely holds.
+
+---
+
+## The double-count rule
+
+The pulse potentially sees revenue in four places: the ledger, a processor, a storefront, and a POS.
+
+**Pick one revenue source and say which.** Summing them inflates the number, sometimes by more than double, and an owner who spots that stops trusting the whole pulse.
+
+Order: the ledger first (whichever is connected; if two, the owner's named source of record), then the processor, then the storefront. Everything below the chosen source supplies detail — channel splits, product splits, settlement timing — not totals.
+
+```
+Revenue — AUD 43,200 MTD (source: Xero; Shopify used for product mix)
+```
+
+### One source double-counts too
+
+Picking a single source is not enough. QuickBooks own sales-by-customer summary returns two rows for any customer that has sub-customers or jobs beneath it: a summary row for the parent, and a separate total row carrying the identical figure. The report's built-in top-customer list includes both.
+
+So a customer appears twice in any ranking built straight off those rows — once under its own name, once as "Total for" that name — and every concentration figure computed from them is overstated.
+
+Drop rows whose metadata type marks them as a total before ranking or summing. Keep the parent summary row. This is a guaranteed error on any book that uses jobs or sub-customers, which in the trades is most of them.
+
+---
+
+## Scheduled presets
+
+| Preset | When | Shape |
+|---|---|---|
+| Monday | Start of week | Full pulse, forward-looking. What's coming, what needs attention |
+| Friday | End of week | Recap. What moved, what closed, what slipped |
+
+Same skill, different framing.
+
+**The two are genuinely different documents.** Monday should lead with the week's commitments and the single most important thing to act on. Friday should lead with what actually happened against what was expected. A Friday recap that reads like a Monday brief is a Monday brief sent on the wrong day.
+
+Offer a cadence once, after a pulse the owner found useful. Don't ask twice.

package/content/small-business/skills/small-business-call-list/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: call-list
+description: Builds today's call list. Runs lead-triage to rank the top-5 leads most worth calling, supplies talking points from email history, blocks time on the calendar, and drafts follow-up messages. Trigger on "call list," "who am I calling today," "top five to call today," or "block time for calls." An owner who wants leads scored or ranked with no calendar blocks routes to lead-triage directly. Accepts optional count and date arguments.
+allowed-tools: Read, WebFetch
+---
+
+Run the lead prioritization. Scan the pipeline, rank by urgency and opportunity, pull relevant email context, and get the owner ready to make calls.
+
+Parse arguments:
+- `--n` (default: `5`) — number of leads to surface (1–10)
+- `--date` (default: today) — date to build the call list for (`YYYY-MM-DD`)
+
+## Step 1 — Pipeline scan (lead-triage)
+
+Run the `lead-triage` skill workflow for the pull and the scoring — it owns the HubSpot field list, the four-dimension model, the note-body urgency fetch, the flat-score guard, and the enrichment leg (with Apollo or Clay connected, company fit for leads that have no company on file — metered, so lead-triage asks once about the credit cost; pass that question through to the owner rather than answering it). Do not rebuild any of that here. Then pull email threads from Mail for each surviving lead (last 3 emails per contact) for the talking points.
+
+## Step 2 — Rank and select top N
+
+Take lead-triage's ranking and select the top `--n` — always exactly `--n` when that many leads exist, regardless of pipeline size. For ties, prefer leads with unanswered inbound signals. If lead-triage reports flat scores, present its CRM-fact ladder order instead and say so.
+
+For each selected lead, produce a call card:
+
+```
+{Rank}. {Contact Name} — {Company}
+Deal: {currency code} {amount} | Stage: {stage} | Last contact: {X days ago}
+Signal: {most recent activity}
+
+TALKING POINTS
+• {point from email/deal context}
+• {point from email/deal context}
+• {open question to ask}
+
+GOAL FOR THIS CALL: {one sentence — advance to next stage / re-engage / close}
+```
+
+## Step 3 — Calendar block
+
+For each lead on the list, offer to block 20 minutes on the owner's calendar for the target date.
+
+Show the proposed calendar entries:
+```
+{time slot} — Call: {Contact Name} ({Company})
+```
+
+Wait for owner to confirm which calls to block before creating calendar events.
+
+## Step 4 — Draft follow-ups
+
+For any lead that has an unanswered email older than 3 days, draft a brief follow-up:
+```
+Subject: Re: {thread subject}
+
+Hi {first name},
+
+{One sentence referencing prior conversation}. {One sentence with a clear next step or question}.
+
+{Sign-off}
+```
+
+## Connector failures
+
+If HubSpot is unreachable, stop and tell the owner — lead scoring requires CRM data. If Mail is unreachable, skip the email-context pull in Step 1 and the follow-up drafts in Step 4, and note "Mail not connected — email context and follow-up drafts skipped" in output; calendar blocking in Step 3 still runs. If Google Calendar is unreachable, skip calendar blocking and note it. If the lead-data connector is unreachable or the owner declines the enrichment spend, company fit stays flat for leads with no company on file — say so in the output rather than presenting the order as fit-ranked.
+
+## Approval gates
+
+- **Never send emails automatically.** Present drafts for owner approval only.
+- **Never create calendar blocks without owner confirmation** — show the proposed list first.
+- **Never update HubSpot deal stages automatically.**
+
+## Output
+
+Present the ranked call list with talk tracks. Then show proposed calendar blocks and ask for confirmation. Then show follow-up drafts and ask which to send.
+
+Alongside the chat summary — never replacing it — render the list as a CALL SHEET artifact using the house style (`../../shared/artifact-style.md`): something the owner prints and works from while dialing. Print-friendly rows, one per lead, each with the call goal and two or three short talking points, plus a blank outcome line to scribble on. This is a work sheet, not a dashboard — no stat tiles, no charts.
+
+## Closing offer
+
+Close with one line on what got built, then the single most relevant next step with its trigger phrase — usually "write this outreach" (`outreach-composer`) for the leads that need email instead of a call. Up to two others: "fill my funnel" (`/grow-pipeline`) or "update the CRM" (`crm-autopilot`). Max three, and skip anything the owner declined earlier this session.
+
+## 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.