| 1 | --- |
| 2 | name: cold-read |
| 3 | description: Review anything you are about to hand to a person (screenshot, GIF, chart, UI state, user-facing string, error message, PR or commit body, report) as a reader with no context, before it ships. Use this before sending an image or chart, before reporting a UI change done, before filing a PR or writing a commit message, and before any string a user will read. It catches what the author cannot see after working with full context. Cut-off text, jargon, dead ends, demo-only data and claims nobody can judge without the thread. Lighter than the whole-app tester in `ux-testing`. |
| 4 | --- |
| 5 | |
| 6 | # Cold read |
| 7 | |
| 8 | After hours in a task, every gap in the artifact is filled in by what you know. |
| 9 | You read "needs ACP adapter" and see a precise term; the owner sees nonsense. |
| 10 | Re-reading with that context passes the same flaws, so the check has to run in a |
| 11 | reader who never had it. |
| 12 | |
| 13 | `AGENTS.md` says when: anything that leaves the thread. This skill says how. |
| 14 | `ux-testing` ("fresh eyes") drives a whole app as a first-time user; this is the |
| 15 | per-artifact version of the same idea. |
| 16 | |
| 17 | ## 1. Make the artifact the thing the reader sees |
| 18 | |
| 19 | - Review the output, not its source: the PNG, the rendered page, the final PR |
| 20 | body, the string as it appears in the UI. |
| 21 | - Use real data. A fixture that happens to fit hides truncation, `0.00`, odd |
| 22 | ordering, and entries the owner did not expect to see. |
| 23 | - Capture every state a person can land in (empty, long, error, narrow), not just |
| 24 | the happy one. |
| 25 | |
| 26 | ## 2. Self pass, every time (cheap) |
| 27 | |
| 28 | A screenshot script that exits 0 has been tested, not reviewed: the feature |
| 29 | works and the image can still be cropped, blank, stale, or showing the wrong |
| 30 | state. Capture and send must be separate steps, never one script or one call, |
| 31 | and no image goes to the owner (or into a PR, report, or `html_render`) that you |
| 32 | have not opened in this turn. |
| 33 | |
| 34 | Open the file with the image viewer and write down, in plain words, what is on |
| 35 | it before judging. Check that it shows the state you meant to prove, not just |
| 36 | some state. Then check: |
| 37 | |
| 38 | - text ending in `…` (a finding even when intentional, since it reads as cut |
| 39 | off), clipped at an edge, or overlapping something; |
| 40 | - uneven spacing, empty regions, content hugging one side; |
| 41 | - marks with no label: icons, badges, `+1`, colours, ticks; |
| 42 | - a chart's title, axis names, units and legend. Can its claim be read at a |
| 43 | glance? |
| 44 | |
| 45 | ## 3. Cold pass (anything past a one-liner) |
| 46 | |
| 47 | Launch a fresh sub-agent on Claude Sonnet at low effort. It gets the artifact, |
| 48 | one line naming the audience, and the questions for its kind. It never gets the |
| 49 | diff, the thread, the code, or what you meant it to say. When Claude usage is |
| 50 | low, use `gpt-6.1-terra` at low effort instead, and check geometry and |
| 51 | affordance yourself in the self pass (see "Choosing the reader"). |
| 52 | |
| 53 | ``` |
| 54 | You are <audience, e.g. "a developer who has never seen this app">. You have |
| 55 | only the attached <artifact>. Do not read any code or docs. Say in two |
| 56 | sentences what you think it shows or does. Then list at most three things a |
| 57 | real person would stop or misunderstand at (confusing, cut off, undefined, |
| 58 | misleading, missing), worst first, one line each: what you saw → what you |
| 59 | expected. Skip taste and polish. Do not say whether you like it. If it is fine, |
| 60 | say "nothing" and stop. |
| 61 | |
| 62 | Questions: <rows from the table below> |
| 63 | ``` |
| 64 | |
| 65 | A reader that cannot restate the artifact correctly in its first two sentences |
| 66 | is the finding. |
| 67 | |
| 68 | | artifact | ask | |
| 69 | |---|---| |
| 70 | | screenshot, UI state | Is any text cut off or any gap uneven? What can I do next, and can I undo it? Which things are buttons? | |
| 71 | | UI copy, labels | Is every word and symbol defined for someone who just arrived? Does anything use the project's internal vocabulary? | |
| 72 | | chart | What is the claim? Are axes, units and legend present? What would a skeptic say is missing? | |
| 73 | | generated or computed content | Does anything look wrong for a real input (rounding, ordering, casing, an item that shouldn't be there)? | |
| 74 | | form of the content | What does the reader decide from this, and is this the shape that serves that decision? | |
| 75 | | PR, commit, issue body | Can a reviewer judge each claim without the thread? Is the size justified in the first lines? Is anything stated that the reader cannot verify? | |
| 76 | | error or status | What happened, whose fault is it, what do I do? | |
| 77 | |
| 78 | ## Choosing the reader |
| 79 | |
| 80 | Measured on 18 screenshots (9 with one planted flaw each, 9 fixed controls) at |
| 81 | low, medium and high effort. Single runs, blatant flaws only; subtle ones such |
| 82 | as a 2px misalignment are untested. |
| 83 | |
| 84 | | reader | planted flaws caught | findings per image | misses | |
| 85 | |---|---|---|---| |
| 86 | | Claude Sonnet, any effort | 9/9 | 3.3–4.1 | none | |
| 87 | | gpt-6.1-sol | 6–8/9 | 1.1–1.4 | unclickable menu, uneven padding | |
| 88 | | gpt-6.1-terra, any effort | 7/9 | 0.9–1.1 | unclickable menu, uneven padding | |
| 89 | |
| 90 | - More effort never caught more; on Sonnet it only added nitpicks, so use low. |
| 91 | - Sonnet sees layout and affordance the others miss, and its extra findings are |
| 92 | mostly polish, which the three-finding cap in the brief removes. |
| 93 | - Terra is solid on meaning, cut-off text, rounding and missing labels, and |
| 94 | stays quiet on clean images. It misses pure layout and affordance, so as the |
| 95 | fallback the self pass must check spacing and "what looks clickable" itself. |
| 96 | - Sol offers nothing over Terra here. Do not use opus- or fable-class models. |
| 97 | |
| 98 | ## 4. Act on it |
| 99 | |
| 100 | - Fix every real confusion and re-render. Re-run the cold pass once if the fix |
| 101 | changed layout or wording substantially. |
| 102 | - Findings about taste or direction go to the owner as a question. The cold |
| 103 | reader cannot judge taste, so never ask it whether something is good. |
| 104 | - Report the fix in one line after the artifact, never before it. |
| 105 | |
| 106 | ## Where it has already failed |
| 107 | |
| 108 | Owner complaints this skill exists to prevent: a "Use reset link" cut off to |
| 109 | `Use…`; "needs ACP adapter makes no sense to me"; "unclear where you get this |
| 110 | key from"; "I can't tell what is a button"; "a learning rate reads 0.00"; |
| 111 | "deepseek is showing up here"; "displaying a table is kind of wrong"; "+4800, |
| 112 | what the heck". |