# Voc Orchestrator

> Run the full Voice of Customer pipeline end to end — pull every configured source, analyze calls, profile signals, synthesize confirmed patterns, route them, and generate artifacts. The one weekly command. Trigger on /voc-orchestrator, "run the VoC pipeline", "do the weekly customer intelligence run".

- Skill: `aatirar/voc-orchestrator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aatirar/voc-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aatirar/voc-orchestrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: aatirar (https://skillmd.com/u/aatirar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aatirar/voc-orchestrator

---


# /voc-orchestrator — The Weekly Run

One command, six phases. The intelligence lives in the individual skills; this is a coordinator
that runs them in order and fails loudly instead of quietly.

## Arguments

| Flag | Effect |
|---|---|
| `--window 30d` | Override the default window |
| `--skip-sources chat,notes` | Skip named sources |
| `--dry-run` | Pull, analyze and synthesize, but do not route or dispatch |
| `--sources-only` | Stop after Phase 1 |

**Use `--dry-run` for your first three runs.** Read the synthesis by hand and check whether the
confirmed themes match what you already believe from talking to customers. If they do not, the
problem is almost always upstream configuration, not the rule.

---

## Phase 0 — Preflight

Before pulling anything, verify the setup and **print the result as a table**. Do not proceed
silently past a broken connector.

```
Preflight
  config/thresholds.json        ok
  context/product-context.md    ok
  CALL_PROVIDER=gong            credentials present
  Apify MCP                     connected
  CRM MCP                       NOT CONNECTED — signals will be tier U
  chat_channels                 3 configured
  notes_source                  not configured — skipping
  VOC_OUTPUT_DIR=./outputs      local, not synced   ok
```

Check `VOC_OUTPUT_DIR` for the strings `Dropbox`, `Google Drive`, `OneDrive`, `iCloud`. If it is
inside a synced folder, **warn before writing anything**. This pipeline writes customer
conversations to disk.

If fewer than `confirmation.min_independent_sources` sources are configured, say plainly that
nothing can reach high confidence this run, and suggest either connecting more sources or
lowering the threshold deliberately in the config.

---

## Phase 1 — Pull sources

Run in parallel where the connectors are independent:

| Order | Skill |
|---|---|
| 1 | `/voc-source-calls` |
| 2 | `/voc-source-reviews` — **cost guard**: this one spends money. Skip on weekly runs; monthly is enough. Reviews do not change fast. |
| 3 | `/voc-source-chat` |
| 4 | `/voc-source-notes` |
| 5 | `/voc-source-custom` for each registered custom source |

A source that is not configured is skipped, not failed. A source that is configured and errors
**stops the run** — a partial corpus produces a confident-looking synthesis built on a hole.

## Phase 2 — Analyze calls

`/voc-analyze-calls`. Its report is a structured corpus and feeds synthesis directly rather than
being profiled signal by signal.

## Phase 3 — Profile

`/voc-profiler` over every unprofiled signal in `outputs/voc/sources/`. Parallelize with subagents
above 20 signals, respecting `cost_guards.max_parallel_subagents`.

**Deduplicate before profiling**, not after. Cross-source duplicates are the one failure the
confirmation rule cannot catch, because by the time it runs they look independent.

## Phase 4 — Synthesize

`/voc-synthesize`. Clusters via subagents, then applies the rule via `scripts/synthesize.js`.

## Phase 5 — Route

`/voc-route`. Skipped under `--dry-run`.

## Phase 6 — Dispatch

`/voc-dispatch`. Skipped under `--dry-run`. Produces drafts only. Nothing is sent.

---

## Final summary

```
VoC Pipeline — week of 2026-04-20 to 2026-04-26

  SOURCES          calls 41 · reviews skipped (monthly) · chat 23 · notes 8 · custom 0
                   duplicates removed 6
  PROFILED         72 signals    tier A 9 · B 41 · C 8 · U 14 (quarantined)
  CALLS ANALYZED   41 in → 12 internal · 8 customer · 21 prospect
  SYNTHESIS        34 clusters → 6 confirmed · 9 watchlist · 19 dropped
  ROUTED           testimonial 2 · case study 1 · objection 3 · product 4 · exec 1
  DISPATCHED       11 artifacts, 1 held

  Not available this run: CRM (not connected) — all weighting is ICP-only
  Runtime 14 min

  Start here: outputs/voc/synthesis/2026-04-26-synthesis.md
```

Always end with the single file a human should open first.

---

## Cadence

**Weekly** is right for calls, chat and notes. **Monthly** for reviews — they move slowly and each
run costs money. **Quarterly**, run a wide window to see what has been steadily true rather than
what happened last week.

Daily runs are a mistake. The confirmation rule needs time to accumulate corroboration across
channels, and a daily cadence produces a watchlist that never graduates.

---

## When it goes wrong

The orchestrator is deliberately thin. If output looks wrong, run the phases by hand — the
failure is almost always in one skill and obvious once isolated.

| Symptom | Usual cause |
|---|---|
| Everything is tier U | CRM not connected, or company names not resolving |
| Nothing confirms | Too few channels configured, or duplicates were removed correctly and you genuinely have thin signal |
| Everything confirms | Duplicate signals counted as independent channels. Check Phase 3 dedup first. |
| Quotes sound like your own marketing | Speaker labels missing on transcripts, so internal speakers are being harvested |
| Same theme every week | It is either genuinely your biggest problem, or one loud account. Check the account spread. |