Role-based review
My agent rebranded my Stream Deck app and missed an old logo. So I asked it to review the work as a new user, a store reviewer and a code reviewer. Here is how that works, and how to do it on your own work.
- Where
- In the terminal, with Claude Code
- Size
- A quick one
- Short link
- piy.show/s010
The agent did the big task and missed a little thing
I had to rebrand my Stream Deck app, Dial It Countdown. The name, the logo, the code and the store screenshots all had to change. I gave the agent the task, and it did the big job well.
Then it told me it was done. One key on the device still showed the old logo. The support link still pointed at the old GitHub name. Little things, and exactly the things a customer or a store reviewer sees first.
Why does this happen? The agent that builds the thing checks what it meant to make. It reads its own work the way you read your own email: it sees what it intended, not what is on the screen. Asking it to double-check does not help much, because it checks with the same eyes.
Why did the agent miss the old logo? Prompt it yourself
List every place the old name, the old logo and the old links still live in this project. Change nothing yet.
Give the reviewer a role
Role-based review is one agent, several roles. Each role has its own goal and its own checklist in its head. A new user asks: is anything confusing, broken, or still old? A store reviewer asks: do the screenshots, the links and the description follow the rules? A code reviewer asks: is the old name still in the code?
The role changes what the model looks for. Say double-check and it has no goal, so it skims. Say you are the Marketplace reviewer and it goes to the listing, the screenshots and the support link, because that is what that person checks.
How to pick the roles: ask who would normally review this work before it goes out, and who pays for a mistake. The first person to use it. The person who approves it. The person who has to fix it later. Three roles is plenty. Make them different from each other, or they find the same things three times.
Which roles should review my work? Prompt it yourself
Before I ship this, who would normally review it, and what would each of them look for? Give me three roles that look at different things.
How to write the prompt
My prompt has four parts, and they are the same for any work.
First, the work. In the terminal the agent sits in the folder, so it reads the files itself. In a web chat you paste the text or the screenshots in.
Second, the roles, numbered. Third, one question for each role. One question keeps the role focused; a role with five questions becomes a general reviewer again.
Fourth, the ask at the end: list what each one finds, then fix the issues you identified. The list comes first, so you can read what it found before anything changes. The fix comes second, so you do not have to ask twice.
How do I write a role-based review prompt? Prompt it yourself
Review this rebrand as three reviewers. 1. A new Stream Deck user: confusing, broken, or old? 2. A Marketplace reviewer: screenshots, links, rules? 3. A code reviewer: is the old name left in the code? List what each one finds, then fix the issues you identified.
What it caught
The new user found the old logo on one key. The Marketplace reviewer found the support link still pointing at the old GitHub name. The code reviewer went through the code for the old name.
Different roles, different finds, and all of them before I submitted the app. A rejection from the store costs days. The review cost a few minutes.
Read the list before you let it fix. Not every find is right, and some you want to decide yourself. Tell it which ones to fix and which ones to leave.
What did the reviewers find in the rebrand? Prompt it yourself
Fix 1 and 2 from your list. Leave 3 for now, and show me where you found it before you change anything.
Your CV
Your CV has two readers, and they read it differently. The recruiter reads thirty CVs an hour and asks one thing: shortlist or not? They look for the job title, the words from the ad, the dates, and anything missing. The hiring manager reads the shortlist slowly and asks: where is the evidence this person can do the job? Led a redesign is a claim. The redesign halved the sign-up time is evidence.
Give the agent the job ad with the CV. Without it the recruiter role has nothing to match against.
Which roles should review my CV? Prompt it yourself
Here is the job ad and my CV. Review the CV as two reviewers. 1. The recruiter: would you shortlist me for this role, and what is missing? 2. The hiring manager: where is the evidence I can do the job? List what each one finds, then fix the CV.
I can help you build yours
I build things like this with an AI agent, on my own computer. In a private session I help you do the same with your idea. Or bring it to the show, free.
A trip with the kids
Imagine you planned a trip with the kids, and you are vegetarian. The plan looks fine to you, because you wrote it. A parent who travels with young kids reads it and sees a twelve kilometre hike at four in the afternoon for a six year old. A vegetarian reads it and sees no meal near two of the stops.
The roles only work with the context. Give the agent the itinerary, the kids' ages and what you eat. It cannot check what it does not know.
How do I give the agent my trip plan? Prompt it yourself
Review this trip plan as two reviewers. 1. A parent: is it realistic for kids aged 6 and 9? 2. A vegetarian: is there a vegetarian meal near each stop? List what each one finds, then fix the plan.
Roles for other work
The pattern is the same for almost anything. Who sees it first, who approves it, who pays for the mistake.
A website: a first-time visitor on a phone, and someone who needs to find the price in ten seconds. A contract: the other side's lawyer, and you in a year when something goes wrong. A pitch: the investor who has seen a hundred, and a customer who does not care about the technology. An email: the busy person who reads only the first two lines.
What roles would review a website? Prompt it yourself
Review this as two reviewers. 1. The person who sees it first: what stops them? 2. The person who approves it: what is missing? List what each one finds, then fix it.
When the list comes back empty
A few things I learned. Roles that overlap find the same things twice: a tester and a QA engineer are one role. More than three or four roles, and the list gets long and the finds get thin. Ask for finds, not opinions: a reviewer asked what do you think says it is great.
And if the list comes back empty, the roles were wrong or the context was missing. The work is not perfect. Change the roles and run it again.
How many roles should I use? Prompt it yourself
Your list is empty. Which three roles would be hardest on this work, and what would each of them look for?
Not just double-check
So next time, do not ask your agent to double-check. Think about who would normally review your work, and what each of them looks for. Give it those perspectives, let it list what it finds, and then let it fix.
Start in the terminal below, in the folder of the work. And just prompt it yourself.
How do I try this on my own project? Do it in the terminal
I do this with Claude Code, the AI agent in the terminal. It works in a folder on your own computer, so it reads your files every time and can look things up for you.
A web chat works too, but there you paste everything in again in every new chat.
-
Get Claude Code
It comes with Claude Pro, US$20 a month, paid to Anthropic. Claude's plans
-
Make a folder for it, and open it
mkdir -p ~/projects/my-app && cd ~/projects/my-app
-
Start the agent
claude
-
Ask it
Review this rebrand as three reviewers. 1. A new Stream Deck user: confusing, broken, or old? 2. A Marketplace reviewer: screenshots, links, rules? 3. A code reviewer: is the old name left in the code? List what each one finds, then fix the issues you identified.
Never opened a terminal? In a private session I put Claude Code on your computer with you, and you start your first idea.
Prompty