---
sharksapi_version: p-aeed6dd3d6
name: voice-of-customer
description: Collect and synthesize real customer language and evidence — reviews, surveys, support tickets, CRM notes, communities, emails — into Jobs to Be Done, pains, triggers, objections, purchase criteria and money quotes with full source provenance. Produces practical outputs for positioning, ad angles, landing copy, social topics, SEO opportunities and sales enablement. Never invents quotes; aggregates and anonymizes; proposes (never silently applies) marketing-context updates.
allowed-tools: [memory_bootstrap, memory_search, memory_write, get_team_capabilities, list_connections, get_surveymonkey_surveys, get_surveymonkey_details, get_surveymonkey_responses, get_google_forms, get_google_form_responses, get_jotform_forms, get_jotform_submissions, trustpilot_get_reviews, g2_get_reviews, g2_get_competitors, capterra_get_reviews, get_google_business_reviews, get_social_mentions, search_web_mentions, get_zoho_desk_tickets, get_gorgias_tickets, get_pipedrive_deals, get_pipedrive_contacts, get_pipedrive_activities, get_emails, scrape_website, search_drive, get_drive_file_content, notion_search, read_dashboard, update_strategy_task, submit_draft, revise_draft]
metadata:
  role: research / content agent
  triggers: [voice of customer, voc, customer research, what customers say, customer quotes, review mining, why do customers buy, churn reasons, customer pain points, jobs to be done, kliendi hääl, kliendiuuring]
  sources: "Adapted for SharksAPI from coreyhaines31/marketingskills customer-research skills (MIT, © 2025 Corey Haines). Synthesis, not verbatim copy."
---

# Voice of Customer (VoC)

Collect real customer language and evidence, synthesize it into usable marketing intelligence, and hand every downstream agent (positioning, ads, landing pages, social, SEO, sales) words that customers actually said instead of words a model made up.

**Evidence discipline is the whole skill:**
- Every important finding carries **provenance** (source tool, item id/date, segment).
- Direct quotes are marked as quotes and reproduced verbatim; summaries are marked as summaries. **Never invent, embellish or "reconstruct" a quote.**
- Evidence (what people said) is kept separate from interpretation (what you conclude).
- Personal data never enters public dashboards, drafts or shared artifacts — aggregate and anonymize ("agency owner, 11–50 employees, churned Q2", never names/emails).

All JSON snippets are `params` payloads for `POST https://sharksapi.ai/api/v1/a2a`. Inspect the live tool schema first (`GET /api/v1/a2a/tools`) — VoC source availability varies enormously per project.

## Phase 0: Orient and scope

1. `{"tool": "memory_bootstrap", "arguments": {}}` — marketing context (especially `context:icp`, `context:positioning` — you will test these against evidence) and any prior `voc:*` entries (`memory_search` "voc:").
2. `read_dashboard` (own token) — the requesting task and its question. A VoC run needs a scoped question ("why do trials churn?", "what language for the new landing page?") — an unscoped "do VoC" defaults to: top pains, JTBD, objections, purchase criteria for the primary ICP.
3. `list_connections` — inventory which sources below are LIVE. Report the inventory (available vs missing) at the top of your output.

## Phase 1: Collect from every available source

Pull whatever is connected; skip and name what isn't:

| Source type | Tools |
|---|---|
| Reviews (own + competitor) | `trustpilot_get_reviews`, `g2_get_reviews` (+ `g2_get_competitors`), `capterra_get_reviews`, `get_google_business_reviews` |
| Surveys & forms (incl. NPS) | `get_surveymonkey_responses` (+ surveys/details), `get_google_form_responses`, `get_jotform_submissions` |
| Support | `get_zoho_desk_tickets`, `get_gorgias_tickets` |
| Sales/CRM | `get_pipedrive_deals` + `get_pipedrive_activities` (notes, lost reasons), `get_pipedrive_contacts` for segment attributes only |
| Email conversations | `get_emails` (mine threads for questions/objections — handle with extra PII care) |
| Communities & web | `get_social_mentions`, `search_web_mentions` (Reddit/forums where indexed), `scrape_website` for public forum/competitor-review pages the human points at |
| Documents | `search_drive`/`get_drive_file_content`, `notion_search` — interview notes, call transcripts, past research |

Practical bounds: recent-first, cap volume per source (e.g. last 100–300 items) and say what was sampled vs exhaustive. Competitor reviews are gold for switch triggers and objections — read low-star reviews of competitors and of the project alike.

## Phase 2: Extract (evidence layer)

Tag each meaningful item with: source + id/date, segment attributes (anonymized), and one or more of —

- **Job to Be Done** (functional; also emotional and social jobs)
- **Pain point** (with intensity: casual mention vs deal-breaker language)
- **Trigger event** (what pushed them to look for a solution)
- **Desired outcome** (in their words)
- **Objection / hesitation** and **alternatives considered**
- **Purchase criteria** (what they compared on)
- **Money quote** — verbatim, vivid, usable in copy (mark VERBATIM + source)

Keep a raw extraction table; the synthesis must be traceable back to it.

## Phase 3: Synthesize (interpretation layer, clearly separated)

- **Theme frequency and intensity**: how often each pain/JTBD/objection appears AND how strongly worded — a theme mentioned twice is not a "top pain"; report counts (`n=`) per theme per source.
- **Segment differences**: where evidence supports it, split by segment; don't force splits thin data can't carry.
- **Contradictions**: surface them explicitly (e.g. reviews praise pricing, lost-deal notes cite price) — contradictions are findings, not noise to smooth over.
- **Language patterns**: recurring words/phrases customers use (and words they never use — candidate forbidden words for `context:voice`).
- Confidence per finding: strong (multi-source, high n) / moderate / weak (single source, low n).

## Phase 4: Practical outputs

Produce the packages the requesting task needs (not all of them by default):

1. **Positioning input** — JTBD + differentiated-value evidence vs alternatives, for `marketing-context` review
2. **Ad angles** — pains/outcomes/objections ranked by frequency×intensity, each with 2–3 money quotes → feeds `ad-creative-factory`
3. **Landing copy blocks** — headline candidates in customer language, objection-answer pairs, proof themes → feeds `ads-landing` / web work
4. **Social topics** — questions customers actually ask, contrarian takes evidence supports → feeds `social-content-agent`
5. **SEO/content opportunities** — problem phrasings customers use that content doesn't cover → feeds `keyword-research` / `content-strategy`
6. **Sales enablement** — objection handling matrix, switch triggers, competitor weak points → feeds sales agents

Each output item cites its evidence (theme, n, example quote + source).

## Phase 5: Store, propose, verify

1. Write durable findings to shared memory, prefixed `voc:`, with provenance and confidence:

```json
{"tool": "memory_write", "arguments": {"scope": "channel:content", "type": "result",
 "title": "voc:top-pain-onboarding",
 "content": "2026-07-10: Onboarding effort = #1 pain (n=23/140 reviews G2+Trustpilot, 8 high-intensity). VERBATIM: \"took us three weeks to see any value\" (G2, 2026-03). Confidence: strong. Full table: {where}."}}
```

2. **Propose — never silently apply — context changes**: stable, confirmed findings that contradict or extend `context:*` (ICP, positioning, voice) go to the orchestrator/manager as a proposal (`submit_draft`, type `web_text`, title "VoC → marketing context proposals", or a dashboard action item). `marketing-context.skill.md` Update mode + human confirmation owns the actual change.
3. Deliver the report where the task asked (document/dashboard/draft). PII check before delivery: no names, emails, company-identifying quotes without consent — redact inside quotes where needed (marked `[redacted]`).
4. Mark the strategy task complete (`update_strategy_task`) only after the deliverable is delivered and stored — with a note pointing to the memory entries.

## Failure & fallback

- Few/no sources connected → say so up front; work what exists (even website testimonials + public reviews), label the confidence ceiling, and recommend which ONE source to connect next for the biggest evidence gain.
- Zero customer evidence available → do not fake a VoC study; deliver a collection plan (what to connect/export, survey questions worth asking) instead.
- Contradiction with existing positioning → report it as a finding with evidence; never rewrite `context:*` yourself.

## Sources & attribution

Extraction/synthesis framework adapted from Corey Haines' *marketingskills* customer-research skills (MIT, license verified 2026-07-10), rebuilt on SharksAPI's review/survey/support/CRM tooling, provenance-first memory conventions and the marketing-context proposal flow.