# Voice of Customer skills for Claude Code

**A VoC pipeline that refuses to report a pattern until several independent channels agree.**
Pulls from call recordings, review sites, internal chat, meeting notes and anything else you
wire up. Weights each signal by who said it. Reports only what corroborates. Routes the result
to the person who can act on it, with the customer's exact words attached.

Most "AI for customer feedback" workflows stop at *summarize this*. A summary of a hundred
conversations is a paragraph nobody acts on, and the human is still the bottleneck. This is the
system version: signal in continuously, confirmation applied mechanically, human attention spent
only on judgment calls.

---

## What it produces

Here is the shape of the output. Company names are fictional and the numbers are illustrative —
**this is a format example, not a real run.**

```
SYNTHESIS — rule: 3+ independent channels, or 2+ with a tier-A account. Minimum 3 mentions.
──────────────────────────────────────────────────────────────────────────────
34 clusters in → 6 confirmed · 9 watchlist · 19 dropped

CONFIRMED
  [HIGH  ] Export is slow on large datasets
           pain · 11 mentions · 3 channels (call, review, chat) · 7 accounts · A:2 B:8 C:1
           3 independent channels
           +4 unattributed signal(s) excluded from the count

  [HIGH  ] Cannot buy without SSO
           request · 6 mentions · 2 channels (call, ticket) · 4 accounts · A:2 B:4
           2 channels including a tier-A account

  [MEDIUM] Onboarding felt long
           pain · 5 mentions · 2 channels · 1 account · B:5
           2 channels, no tier-A contributor — downgraded: all mentions from one
           account (Northwind Trading)

WATCHLIST (single channel — not reported, kept for corroboration)
  · Reporting filters are confusing (review, 3 mentions)

DROPPED (19) — kept in 2026-04-26-dropped.json for traceability
```

That last downgrade is the point of the whole thing. Five mentions of a pain looks like a trend
right up until you notice they are all the same customer. This pipeline checks the account
spread in code, every time, so nobody has to remember to.

---

## What this gets wrong

Read this before you trust anything it outputs.

- **The confirmation rule is a heuristic, not a truth test.** Three channels can all reflect one
  loud market segment. It filters noise; it does not establish fact.
- **Every source is a biased sample.** Sales calls only contain people who took a meeting.
  Reviews only contain the delighted, the furious, and the incentivized. Chat only contains what
  a colleague found notable enough to paste. None of these is your market.
- **Adding connectors makes confirmation easier, not truer.** Wire up six channels and things
  start confirming that should not. Raise `min_independent_sources` when you add sources.
- **Cross-source duplicates manufacture confidence.** The same complaint relayed in chat,
  captured on a call, and filed as a ticket is one event, not three. Deduplication happens
  before profiling, and if you skip it the rule cannot save you.
- **It cannot tell you what nobody said.** The biggest reason people do not buy is usually
  invisible to every source here.

---

## Verify it in thirty seconds

```bash
git clone <this-repo> && cd voc-claude-skills
npm install
npm run check
```

`npm run check` validates every skill's frontmatter, catches lowercase `skill.md` files that
break on Linux, scans for absolute paths and leaked credentials, syntax-checks every script, and
confirms the threshold config parses. No credentials needed. It exits non-zero on failure, so it
works in CI.

Then, with nothing configured yet:

```bash
node scripts/synthesize.js examples/clusters.sample.json --out /tmp/voc-demo
```

That runs the actual confirmation rule against sample clusters and shows you exactly what
confirms, what goes to the watchlist, and what gets dropped. It is the core of the system and it
runs without an API key.

---

## Architecture

```
  calls · reviews · chat · notes · custom
                  │
                  ▼
          /voc-source-*              normalize to one signal shape
                  │
                  ▼
          /voc-profiler              CRM context, ICP fit, weight tier
                  │                  (tier U = unattributed = quarantined)
                  ▼
          /voc-synthesize            cluster by meaning (subagents)
                  │                  apply the rule (code)
                  ▼
          /voc-route                 testimonial · case study · objection map
                  │                  product feedback · exec memo
                  ▼
          /voc-dispatch              outreach emails · copy briefs
                                     PM one-pagers · exec memo
```

**Clustering is judgment, so a model does it. Counting is not, so code does it.** The
confirmation rule lives in `scripts/synthesize.js` reading `config/thresholds.json`, and nowhere
else — it is a threshold you tune, not a paragraph a model interprets differently each run.

## Skills

| Skill | What it does |
|---|---|
| `/voc-orchestrator` | The weekly run. All six phases, with preflight. |
| `/voc-source-calls` | Pull transcripts from your call recorder |
| `/voc-analyze-calls` | Transcripts → prospect intelligence report |
| `/voc-source-reviews` | G2, Capterra and friends → messaging brief. **Costs money.** |
| `/voc-source-chat` | Customer quotes your team pasted into Slack |
| `/voc-source-notes` | AI meeting notes, for the conversations the recorder missed |
| `/voc-source-custom` | Surveys, tickets, CRM email, anything else |
| `/voc-profiler` | Attach CRM context and weight to one signal |
| `/voc-synthesize` | Cross-source confirmation |
| `/voc-route` | Send each theme where it gets acted on |
| `/voc-dispatch` | Generate the actual deliverables |

## Setup

Full walkthrough in **[docs/SETUP.md](docs/SETUP.md)**. The short version:

```bash
cp .env.example .env                                  # call recorder + tokens
cp .mcp.json.example .mcp.json                        # MCP servers
cp context/product-context.example.md context/product-context.md
```

Then fill in `product-context.md`. It takes about twenty minutes and it is the difference between
useful output and generic themes.

**You do not need everything.** The pipeline runs with one source and tells you honestly that
nothing can reach high confidence. Start with calls, add chat, then reviews.

**After connecting any MCP server, run `/mcp` and copy the exact tool names into the relevant
skill's `allowed-tools`.** Tool namespaces differ between servers for the same product, and a
skill that declares a name your server does not expose fails at its first call while looking like
it ran. This is the most common setup failure by a wide margin.

## Cost

Everything is free except review mining, which runs paid scrapers. A four-domain run typically
lands between $2 and $8. Apify's free tier is $5 of credit **total**, not monthly — one wide run
can consume it. See **[docs/COST.md](docs/COST.md)** before your first review run.

## Privacy

This pipeline writes customer conversation transcripts to disk. They are personal data under
GDPR and CCPA.

- Point `VOC_OUTPUT_DIR` at a **local, gitignored** path. Not Dropbox, not iCloud. The
  orchestrator's preflight warns you, but check it yourself.
- Recording laws vary by jurisdiction. This tool assumes you already have lawful recordings.
- Tell your team the chat harvesting is running.
- A public review is not permission to put someone's words in an ad with their logo. Nothing in
  this repo ever marks a quote as approved.

## Requirements

Node 18+. Claude Code. A call recorder with a transcript API is the only near-essential
dependency; everything else is optional.

## Contributing

Adding a call-recorder adapter is the most useful contribution — see
[`scripts/providers/README.md`](scripts/providers/README.md), it is four functions. Run
`npm run check` before opening a PR.

## License

MIT. See [LICENSE](LICENSE).

Frameworks referenced in the skills are credited in [CREDITS.md](CREDITS.md).