Have your agent look at your app the way a customer does

01What this is

What comes back: findings ranked by how much each one costs the reader, and a written design guide built from the rules your best pages already follow.

Before you run this on your own product: use real data. Fixture data skews one way, and that way makes your product look smaller and less capable than it is. Worse, fixtures hide the bug class worth the most: the same item shown twice on one screen with two different numbers and no way to tell which one is right. That only shows up with real data.

02The prompt

Fill the three bracketed blanks in the first paragraph, then paste the whole thing.

You are auditing the web app in this repo the way a careful designer and a first-time customer would, together. The app is: [one sentence: what it is and who uses it]. The person who uses it is: [one sentence: the reader you are protecting, e.g. “a store owner checking this on her phone between orders”]. The app runs locally with: [command, e.g. `php artisan serve`, `npm run dev`], and I can log in with [how].

Work in four passes. Do not skip to fixes. Nothing in this brief asks you to change product code.

## Pass 1: photograph every page, on real data

1. Use real data, never seed or fixture data. Fixture data lies in one direction: it makes a product look emptier and dumber than it is, and it hides the bugs that only show up when two real numbers disagree. If there is no real data locally, stop and ask me for a database snapshot before doing anything else.
2. Enumerate every route a logged-in user can reach (read the router, not the nav). Include detail pages, empty states you can find with real data, error pages, settings, and anything behind a modal or tab. Aim for complete, not representative.
3. Capture each page full-height at desktop width (1440) with a real browser (Playwright or headless Chrome). Force lazy fragments to load before the shot (scroll to bottom, wait for network idle). For mobile, use device emulation (`setDeviceMetricsOverride` with `mobile: true`), not a narrow desktop window: a narrow window produces false overflow and false clipping.
4. Save an index that maps each capture file to its route, the page’s visible title, and the record it shows. Keep the captures at native resolution. Read them in slices at 1x, never a downscaled contact sheet; a contact sheet is for browsing, not for reading numbers.

## Pass 2: derive the design language the app already has

Before judging anything, write down the rules the product is already following on its best pages. Mine, do not invent. For each of colour, type, spacing and shape, data display (numbers, dates, deltas, freshness, empty states), components (buttons, tables, cards, callouts) and voice (how the page talks to the reader), write short rules in this form:

> Rule. One sentence of why, in words the reader would recognise. Breaks if: one concrete thing you could see on a page.

Name the two or three pages that follow the rules best; they are the exemplars every other page will be compared to. Save this as `docs/DESIGN_LANGUAGE.md`. It should be fully readable by a human who has never opened the codebase.

## Pass 3: score every page against the rules

Read every capture against the guide. For each break, record: the route, the rule, what the reader sees (quote the real text and the real numbers on the page), and what it costs them (confusion, a wrong decision, lost trust, wasted scroll).

Then group by cause, not by page: one wrong component on forty pages is one finding, not forty. Rank findings by pages hit times severity. Pay special attention to:

- Two numbers for one thing. The same subject shown with two values on one screen (two positions, two totals, two dates) with nothing saying what separates them. This is the highest-value class of finding and it only appears on real data.
- Colour that argues with the sentence above it (a “good” green on the column the finding just called a problem).
- Freshness and dates said more than one way on a page.
- Numbers with no floor or no unit doing headline duty (a whole page built around a tiny modelled figure).
- Internal vocabulary on user-facing surfaces (enum values, ids, model names, engineer nouns).
- Anything at mobile width that breaks the app’s own header.

Be honest about what is not a finding. If a complaint turns out to be a capture artifact, an intentional redirect, or something real data already answers, strike it and say so. A struck finding is a result, not a failure.

## Pass 4: deliver something a tired human enjoys reading

Produce a single self-contained HTML folder (one page, a shared stylesheet, only the images it uses) and open it in my browser. Not markdown, not a wall of bullets. Body type 18px, a 68-character measure, a sticky list of findings on the left.

The page opens with what was looked at (how many pages, how many real records, when), how to read the page, and a two-sentence honest verdict on where the app stands. Then each finding, worst first, in this shape:

1. A title a person would say out loud, and an effort tag (S under a day, M a few days, L a week or more).
2. What the reader actually sees on the real page, one or two sentences, with the real words and numbers.
3. Why it costs them something.
4. The fix, in one sentence.
5. The screenshot, inline, captioned with the route and a “look at” pointer to the exact spot. One to three per finding.
6. A blank line marked with my name, so I can mark it up in place or just reply by finding number.

Close with the exemplars (the pages to copy, with their captures), a short “what to fix, in order” list, and the guide’s changes if the audit changed it.

## Rules for the whole job

- Every claim is backed by a capture you can point at. If you cannot see it in a screenshot, it is not a finding.
- Never fabricate a detail about the product or its data. Quote what is on the page.
- Do not touch product code, database rows, or config during the audit.
- Plain prose. No em-dashes, no jargon, no rule numbers in the sentences (put them in a muted line under the heading).
- When a real decision is mine (a threshold, a name, what a rule should say), ask, do not decide. Collect those into one numbered list at the end so I can answer in one line.

03How to use it

1. Fill the three blanks. What the app is and who uses it. The one person you’re protecting (for example, a store owner checking her phone between orders). How the app runs locally and how you log in.
2. Run it from the repo root. Inside an agent with shell and a real browser, pointed at a database holding genuine records. If all you have is seed data, take a snapshot first, then restart.
3. Expect four passes: photograph, derive rules, score, write up. In that order. The agent will want to jump straight to fixes. Don’t let it.
4. Answer the numbered list at the end. Every real judgment call gets collected there instead of guessed at: thresholds, names, exact rule wording. Settle all of it in one reply.

It takes a while and it will burn tokens.