gutcheck 0.1.0: ask a buyer persona where to look

gutcheck shows a Workers AI model a screenshot or a design plan with a buyer persona and prints probabilities for where to look. Four commands, a markdown persona file, about $0.0002 a check, one cargo install line.

By Mackenzie Bowes · mackenzie@mackenziebowes.com · @_mackenziebowes on X

You have a page, or a plan for a page, and you want to know where a particular buyer would stop reading before you spend a person's time on it. gutcheck 0.1.0 does that with one command: it shows a model your screenshot and a persona you wrote, and prints the probabilities that this person feels the page is for them, trusts it, wants to try it, finds it polished or is confused.[1]

The numbers tell you where to look and never approve a design. This is what each command does, what a run printed, what it cost and how to install it.

What does each command do?

gutcheck check shot.png shows Clef-flash a screenshot and a persona. For each persona it prints six things: for me, trust, try, polish, confused, and the feeling the person has first.[1] Pass more than one screenshot, --model clef for the larger model (the home page, onboarding, a sales page), or --repeat N for the mean and spread over N answers per persona.[1]

gutcheck directions directions.md scores plans that are still words. Each ## name heading in a markdown file is one direction, and every persona scores every direction with the larger Clef model. The score is try plus remember plus trust minus confused, averaged over the buyers.[1]

gutcheck polish shot.png parts.json asks Clairic for a 0-10 polish estimate for each named part of a screenshot. parts.json names the parts, for example {"headline": "the big first sentence"}. Clairic samples, so its ranges move a point between runs, and the output gives a median with a 10th to 90th percentile range.[1]

gutcheck ask sends your own question schema to a model with your own state and image and prints the raw answers.[1] gutcheck status shows the month's spend against the cap.[1] --json prints rows for other programs, and --parallel N sets how many calls run at once (the default is 4).[1]

What did a run print?

We ran the example persona from the repository on a 390-pixel-wide screenshot of one of our draft pages.

gutcheck check 01-first-390-light.png --persona try-1-example.md

persona          for me  trust   try  polish  confused  feels first
try-1-example      0.47   0.50  0.35    0.25      0.19  relief (0.11)

Then we scored two plans for a trade's home page. The plans are one sentence each: one opens on a price range and a phone number with the free-quote button under it, the other opens on a photo gallery with the phone number in the footer.

gutcheck directions directions.md --persona try-1-example.md

direction        score  for me  trust   try  remember  confused
Quote first       0.60    0.25   0.28  0.24      0.24      0.15
Gallery first    -0.44    0.09   0.07  0.05      0.11      0.66

And gutcheck polish on the same screenshot with one part, a headline, printed 7 (4-9).

What is a persona file?

A markdown file, written in the second person, that starts "You are". The whole file is sent to the model, so it should describe the person and nothing else.[1] The example in the repository reads: "You are Sam Okafor. You run a four-chair hair salon in a mid-sized town and have for nine years. You book by phone and Instagram, you are on your feet all day, and you look at websites on your phone between clients."[3]

gutcheck finds personas in docs/personas/ from the current folder upward: try-*.md files are buyers, and wont-*.md files are people who would not buy, which check shows only as their average "for me". Use --persona FILE or --personas-dir DIR to point somewhere else.[1]

What does it cost?

The three runs above moved gutcheck's own month total from $8.8323 to $8.8329: about $0.0002 for the one check, and $0.0004 for the directions and polish runs together. Each run used one persona.

The price is Cloudflare's, per million input tokens: $0.038 for Clef-flash, $0.24 for Clef and $0.10 for Clairic. Responses carry no token counts, so gutcheck estimates a call from the text length at 3.5 characters a token and 2,000 tokens for an image.[1]

The cap is US$10 a month unless you set one. GUTCHECK_CAP_USD=25 raises it, or put per_month_usd = 25 under [gutcheck] in ~/.config/gutcheck/budget.toml. Every call is logged to ~/.local/share/gutcheck/calls.jsonl, and a run that would cross the cap is refused with exit code 3.[1]

How do I install it?

You need Rust, a Cloudflare account (Workers AI has a free allowance) and, only for screenshots over 4 MiB, ImageMagick.[1]

cargo install --git https://github.com/mackenziebowes/gutcheck
export CLOUDFLARE_API_TOKEN=...
export CLOUDFLARE_ACCOUNT_ID=...
gutcheck check shot.png --persona examples/personas/try-1-example.md

The token needs Workers AI permission, or you can run wrangler login. The account id can also go on the first line of ~/.config/gutcheck/account_id.[1] It is MIT licensed, and the release is v0.1.0.[2]

How should you read the numbers?

They do not predict whether a design will be approved. In an earlier test of ours (hub ticket 1753), Clef-flash scored 29 of Mackenzie's design reviews on eight criteria, and the combined score ordered approvals no better than always predicting "approve": 18 to 20 of 29 right, against 20 of 29. Read the numbers as a map of where to look, and look.

The order of the questions is fixed, and a test in the repository pins it, because the model reads them in the order given.[1] Costs are estimates, and the log is the only record of them.

What should your agent bring to you?

A persona for your own buyer, in a markdown file, and one screenshot of the page you are about to show someone. Run check, read where "confused" is highest, and look at that part of the page first.

If you're scoring designs with personas and want to compare notes, I'd like to hear how: mackenzie@mackenziebowes.com or @_mackenziebowes.