Voc Source Reviews

/voc-source-reviews — Review Mining to Messaging Brief

Public reviews are the only Voice of Customer source where your competitors' customers write down, in their own words, what they hate about the product they already bought. That is the most directly usable copy input available anywhere, and most teams read maybe twenty of them.

This skill reads several hundred, counts what recurs, and hands back language you can put on a page.

Requires

Always tell the user the estimated cost and wait for confirmation before the first run of a session. Getting a surprise Apify bill is the fastest way to make someone distrust a tool.

Step 1 — Parse arguments

/voc-source-reviews "yourproduct.com" "competitor1.com" "competitor2.com"

First domain is yours. Up to three competitors. Bare domains, no scheme, no path.

With no arguments: read context/product-context.md for domain and competitors. If neither is available, ask once. Do not guess a competitor set.

If more than four domains are supplied, run the first four and say which you dropped.

Step 2 — Choose the actor

Review-site scrapers on Apify appear and break constantly, so do not hardcode one. Call mcp__apify__search-actors for "G2 Capterra reviews scraper", read the top results with mcp__apify__fetch-actor-details, and pick on: last-modified date, run count, and whether the input schema accepts a domain or needs a per-platform product URL.

Record which actor you used in the report. When someone re-runs this in six months and gets different numbers, the actor choice is the first thing they will need to check.

Once chosen, call it once per domain — all calls in a single message so they run in parallel. Use async: false. Runs take 60-180 seconds.

Collect results with mcp__apify__get-dataset-items using the defaultDatasetId from each run. (There is no get-actor-output tool. If you reach for one, you are working from a stale example.)

When a domain returns nothing

Fall back in this order, and report which rung you landed on:

1. Retry with an explicit product URL instead of a bare domain
2. Try a different actor from your Step 2 shortlist
3. Web search site:g2.com "<company>" to confirm the product is even listed
4. Report "no public reviews found" and continue with the remaining domains

A competitor with genuinely few reviews is itself a finding. Say so instead of padding.

Step 3 — Count before you interpret

Write the raw items to outputs/voc/sources/reviews/<domain>-<date>.json, then run:

node scripts/analyze-reviews.js outputs/voc/sources/reviews/<date>/

This does the arithmetic in code: review counts per platform per domain, rating distribution, recency spread, n-gram frequency across cons and pros, and switching-phrase extraction with the source review id attached to every match.

Use its output as your factual base. Do not eyeball frequencies from a JSON blob — a model asked to "rank by frequency" over 400 records will produce a confident ranking with no arithmetic behind it, and that is exactly the claim a skeptical reader tests first.

If the script is unavailable, say in the report that frequencies are impressionistic.

Step 4 — Interpret

Now reason over the counts. Nine sections, in this order.

4.1 Sample quality — lead with this

| Domain | Reviews | Platforms | Date range | Avg rating | Verdict | Under 20 reviews for a domain: mark every downstream claim about it as directional. Reviews clustered in one quarter usually mean a review-generation campaign, and campaign reviews skew positive and shallow. Say so.

4.2 ICP profile (your product only)

From reviewer metadata: roles, seniority, company sizes, industries, and what they used before. Compare against who you think you sell to. The gap is often the most valuable line in the report.

4.3 Pain themes

Group by underlying pain, not by wording. For each: theme, mention count, whether it appears in your reviews, competitors', or both, and two verbatim examples.

Shared pains are category problems — a competitor cannot attack you on them and you cannot attack them. Asymmetric pains are the whole game. Mark which is which.

4.4 Switching triggers

From the extracted phrases (switched from, moved from, we replaced, used to use, migrated off, after years of). For each: what they left, what broke, how long they tolerated it, and what finally forced the move.

The last one is the money. Marketing usually targets the pain; the trigger is what actually starts the buying cycle.

4.5 Delight factors

From four- and five-star reviews. Rank by frequency. Separate what customers say they love from what they say when recommending it to a peer — the second is your referral language and it is usually blunter and better than anything on your homepage.

4.6 Competitor attack surface

Per competitor: their top complaints with counts, the capability gaps reviewers name, and support or onboarding failures. Then mark honestly which of these you actually beat. A gap you share is not an attack vector, and a sales team that pitches one gets embarrassed on a call.

4.7 Competitor strengths

What their customers genuinely praise. These are the things you must either match or deliberately outflank. Do not soften this section.

4.8 Copy-ready phrases

10-15 verbatim lines that are emotionally specific and concrete. Attribute each with platform, role and date. Prefer "I spent three weeks trying to get the badge printer to talk to the registration list" over "great product, easy to use."

4.9 Messaging brief

• Three H1 angles, outcome-led, built on the top pain plus the top delight
• Four value-prop bullets in customer language, "[specific outcome] so that [benefit]"
• Objection-handling lines for the top three recurring complaints about your product
• Differentiation angle per competitor, one or two sentences, grounded in an asymmetric gap
• Five content angles, each tied to a named pattern in the data, with a hook line

Copy constraints for everything you write here: no em dashes, no "it's not X, it's Y", no more than two consecutive negations, and none of robust, seamless, powerful, enterprise-grade, best-in-class, game-changing, effortless.

Step 5 — Output

Save to outputs/voc/sources/reviews/brief-<your-domain>-<YYYY-MM-DD>.md.

Header block:

# Review Intelligence: <Product>
**Date:** YYYY-MM-DD
**Domains:** <list>
**Reviews analyzed:** N across M platforms
**Date range of reviews:** YYYY-MM to YYYY-MM
**Actor used:** <apify actor id>
**Estimated cost of this run:** $N.NN

Lead the body with §4.1 sample quality and §4.3 pain themes. Those are the highest-value sections and a busy reader will not scroll.

Also write brief-<domain>-<date>.json with the structured counts, so /voc-profiler and /voc-synthesize can consume it without re-parsing prose.

What this gets wrong

• Reviews are a self-selected extreme. People write reviews when delighted, furious, or incentivized by a gift card. The quiet middle is absent. This is a language source, not an incidence source.
• Vendor-incentivized reviews cluster. A tight date range plus uniformly high ratings plus short bodies is a campaign, not sentiment.
• Old complaints get fixed. A pain from 2023 reviews may be shipped and gone. Weight recent reviews harder and always show the date range.
• Enterprise buyers rarely post. If you sell six figures, your actual ICP is likely underrepresented on G2 relative to the SMB tier.
• Never quote a competitor's negative reviews in public marketing. Use them to find your angle, then make the point in your own words about your own strength.