/review-proof-sorter

name: review-proof-sorter
description: >
  Turns a business's Google reviews into proof for its service pages. Takes the reviews
  (pasted, or exported as CSV/JSON/text) and the list of service pages, sorts every review
  by the service and the suburb or city it talks about, and writes a proof block for each
  page: the best quotes word for word, the words customers use for that job, the places they
  name, and which pages have too few reviews to prove anything yet. Use whenever a user asks
  to "use my reviews on my website", "sort my Google reviews", "put reviews on my service
  pages", "which reviews go on which page", "turn reviews into proof", "review proof sorter", or
  invokes /review-proof-sorter. Also use when a page audit says a service page has no social proof.
  Produces sorted-reviews.csv and proof-blocks.md. Works with the reviews a business already
  has; for getting more reviews, use the separate Review Engine skill.

Review Proof Sorter: Google reviews into proof on every service page

Most businesses have their best proof sitting on a Google Business Profile, and a service page with none. A review about fixing someone's hot water belongs on the hot water page, because that's the job the visitor on that page needs done. This skill sorts the reviews and hands back a block of proof for each page, ready to paste.

Keep it practical. The deliverable is one proof block per page the owner can add this week.

Bundled resources

• `scripts/review_proof_sorter.py`: sorts reviews by service and place with a keyword first pass,

picks whole-sentence quotes, lists the words customers repeat, writes the outputs. Stdlib only, no network.

• `assets/services-template.csv` and `assets/places-template.csv`: the two input layouts.

Step 1: Get the inputs (don't guess)

If `./business-context.md` exists, read it first and confirm rather than re-ask.

1. **The reviews.** Any of these works:

• Pasted straight into the chat. Save them to `reviews.txt`, one review per block with a

blank line between (keep the reviewer name, date and stars on the first line if they pasted them).

• An export or a reviews-widget download as CSV or JSON. The script reads columns called

text/review/comment, name/author, date, rating/stars and place/location.

• If the business has several Google profiles (several branches), keep which profile each

review came from in a `place` column. Never make up, edit or "tidy" a review. If the user can't get their reviews out, stop and tell them how: open the Business Profile, copy the reviews, paste them here. 2. **The service pages.** The URL and name of each service page. Offer to read the site's menu or sitemap to list them, then confirm the list with the user. 3. **The places** (optional). Suburbs, towns or cities they serve, and the location page for each if they have one.

Step 2: Write the keyword lists (you do this, the user checks)

For each service, write the words a customer would use in a review, not the business's own jargon. A plumber's "hot water system replacement" page gets: hot water; hot water system; water heater; no hot water; heat pump; instantaneous. Save as `services.csv` (layout in `assets/services-template.csv`, keywords separated by `;`). Add suburb aliases to `places.csv` (e.g. "St Kilda; St Kilda East").

Avoid keywords that also show up in general praise ("sales" catches "no sales pitch"; "new" catches everything). Show the user the lists in one short table and ask if anything is missing.

Step 3: Run the first pass

python3 scripts/review_proof_sorter.py --reviews reviews.csv --services services.csv --places places.csv --business "<Business name>" --out "<workspace>/review-proof-sorter"

On Windows, `python3` is often just `python`. Use whichever runs Python 3. The script needs no extra packages. It prints how many reviews landed on each service and place, and how many it couldn't sort.

Step 4: Read and fix the sort (this is the important part)

The keyword pass is a first pass. Now read `proof-blocks.md` and `sorted-reviews.csv` yourself:

• **Wrong matches:** a keyword hit that isn't about that service (e.g. "we designed a new

website" on a migrations page). Move or drop it.

• **Unsorted reviews:** read every one in the "Not sorted" list and assign it by meaning. General

praise with no job in it ("great to deal with, on time") suits the homepage or About page, not a service page. Say so rather than forcing it onto a service.

• **Quotes:** each quote must be whole sentences copied exactly, including the reviewer's spelling.

You may pick a different sentence from the same review if it's more specific (a job, a result, a timeframe, a suburb). Never join sentences from different reviews, never cut words out of the middle, never fix grammar. Then rewrite `proof-blocks.md` as the final version: per page, 3 to 5 quotes, most specific first.

Step 5: Hand over the proof blocks

For each service page give: 1. **Where it goes:** near the top, beside or just under the main call to action, not on a separate reviews page. People read proof on the page they land on. 2. **The quotes** with attribution: first name and last initial, "Google review", and the month and year. Link the block to the Google Business Profile so anyone can check them. 3. **Words customers use:** the phrases customers repeat for this job. Suggest using them in the page's headings and copy where they're true, because that's how buyers describe the job. 4. **Places named:** if reviews name suburbs, add those quotes to the matching location pages too. 5. **Thin pages:** any service with fewer than three reviews. Suggest asking the next few customers for that job for a review that names the job and the suburb.

Finish with a three-line summary: pages covered, pages that are thin, and the one page to update first (the one with the most traffic or enquiries, if the user knows it).

Rules

• **Neve