agentleFS
ChykalophiaChykalophia/cro-research-reporting/skills/voc-research/SKILL.md

voc-research

Skill1 starsChanged 32 days agoMITView on GitHub

This skill should be used for voice-of-customer and qualitative conversion research: mining reviews, support tickets, chat logs or sales calls; designing and analysing on-site polls and post-purchase surveys; coding open-ended responses; planning and synthesising user tests; and building a customer-language bank for copy. Trigger phrases: "what are customers saying", "analyse these reviews", "code these survey responses", "why do people abandon", "customer objections", "survey questions", "user testing plan", "voice of customer", "VoC", "review mining".

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read ./cro-engagement.md first and add any research assets you find (review export, survey tool, ticket system) to its Data & access …

    line 44
  2. Distinctive:

    Keep quotes verbatim and attributable to a source type (review, survey, ticket).

    line 51

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Voice-of-Customer Research

Find out why visitors don't buy by asking and watching real customers, then turn what they say into evidence-tagged hypotheses and copy. This is the research layer the audit and the tests depend on.

Why this skill exists (evidence)

  • AI is good at this part. GPT-4o coded survey open-ends at kappa 0.76 against human coders zero-shot and 0.94 fine-tuned (von der Heyde et al. 2025, https://arxiv.org/pdf/2506.14634). ChatGPT beat crowd-workers on 4 of 5 annotation tasks at about 1/20 the cost (Gilardi et al., PNAS 2023, https://arxiv.org/abs/2303.15056).
  • AI is bad at replacing customers. Synthetic users were idealised and sycophantic next to real study data (NN/g 2024, https://www.nngroup.com/articles/synthetic-users/). Synthetic survey data had half the real variance and flipped the sign on a third of the relationships that differed (Bisbee et al., Political Analysis 2024). Never substitute generated personas or "simulated customers" for this research.
  • Small qualitative samples go far. Five users find ~85% of usability problems; three rounds of five beat one of fifteen (Nielsen, https://nngroup.com/articles/why-you-only-need-to-test-with-5-users/). CXL/Speero's ResearchXL asks for 200+ survey responses for stable proportions.

Methods (pick by question and budget; details in references/methods.md)

QuestionMethodAI's jobHuman's job
What stops people buying?Exit-intent / on-page poll (1 open question)Code and count answersChoose the question and page
Why did buyers buy, and what nearly stopped them?Post-purchase survey (5–8 questions)Code, cluster, pull quotesApprove survey; read a sample
What do customers already say unprompted?Review, ticket, chat, return-reason mining (own + competitors)Extract, code, quantifyValidate codebook on a sample
Where do people get stuck?Moderated or unmoderated user test, 5 per round per segmentDraft tasks; summarise sessionsRun or watch sessions; judge severity
What words do they use?Language bank from all of the aboveCollect verbatim phrases by themePick the ones copy will use

Workflow

  1. Read the brief (./cro-engagement.md): the surface, the funnel step that leaks, the ICP.
  2. Start with what already exists: reviews, tickets, return reasons, past surveys. Mining costs nothing and needs no traffic.
  3. Add the cheapest new signal for the leaking step: a one-question poll on that page, or a post-purchase survey. Question bank in references/methods.md.
  4. Code with the protocol in references/ai-coding-protocol.md: build a codebook from a first sample, have AI code a 50–100 item sample, have a human code the same sample, run scripts/agreement.py, refine until kappa ≥ 0.7, then code the full set. With under ~100 items in total, have a human review every AI code instead and call the themes exploratory. The voc-coder agent runs the AI half.
  5. Quantify and rank themes: share of responses per code, split by segment (new vs returning, device, product line). Keep 2–3 verbatim quotes per theme.
  6. Turn themes into hypotheses: each one names the theme, its share, the page element it maps to, and the lever (Cost, Trust, Usability, Comprehension, Motivation). Hand them to ecommerce-cro-audit for prioritisation and experiment-design for testing.
  7. Build the language bank (references/codebook-template.md has the format) for conversion-copywriting.

Engagement context

Read ./cro-engagement.md first and add any research assets you find (review export, survey tool, ticket system) to its Data & access section.

Related skills

ecommerce-cro-audit (consumes themes as evidence), experiment-design (tests the hypotheses), conversion-copywriting (uses the language bank), report-information-design (presents findings).

Guardrails

  • Report counts and shares with the sample size, never "customers feel" without a number.
  • Keep quotes verbatim and attributable to a source type (review, survey, ticket). Don't paraphrase a quote and present it as verbatim.
  • Strip personal data before sending feedback to any external tool.
  • One survey answer is an anecdote; a theme needs volume or a consistent pattern across sources.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.