cold-reading-documents

cold-reading-documents — purpose and record

Companion to SKILL.md. This file holds only what the skill itself does not: why it exists, what its rules are evidence for, how it was tested, and where it is still weak. Nothing here restates a rule — if the two ever disagree, SKILL.md is the skill.

What it is for

Finding out whether a document actually works for someone who was not there when it was written. You cannot review your own instructions: you know what they mean, so every gap gets patched silently from memory and the document reads as complete.

The method is to hand it to a reader with no context, give them a real job rather than a review request, and then ask what it failed to tell them.

Where it came from

This one is different from the other skills in this package: it was not a lesson extracted from project work. It is the method that was invented to test the others, written down after it kept finding things nothing else found.

Its rules are all things that were learned by getting them wrong first:

• The isolation rule exists because a reader who can look around fills your gaps from the surroundings, and the document scores better than it is.
• The task-not-critique rule exists because "is this doc good?" produces praise and produces it reliably.
• The foreign-domain rule produced the single largest edit made to any of these skills. One document carried a nine-row table of defect types from the image project it was written in; cold-read against furniture photography, medical illustration, architectural rendering and game icons, all four readers independently reported it as dead weight. No amount of self-review had found that, because to the author every row was memorable.
• The bluntness framing — saying in those words that this is a test of the document, not of the reader — is what separates a graded essay from a usable list.

How it was tested

Two cold reads, using its own method on itself.

The reader-identity finding was the big one. Model readers are cheap, parallel and renewable — you can run four and then four more after each edit. Human readers are single-use: once someone has read the document they are permanently no longer cold. Every piece of advice about running multiple rounds silently assumed the first kind. That section now leads the file.

The API run added two more: a colleague who already knows the subject is not a cold reader at all — the most common false pass there is — and some documents are domain-locked, because an API guide's domain is that API and you cannot hand it a task from another field. There, varying the shape of the scenario is the only lever, and it is the stronger one anyway.

A scenario prompt template was added because both readers pointed out that the file called the scenario "the instrument" and then never showed one end to end.

Known weak points

• Every example in it is still from one project. Both readers noticed. The description promises runbooks, READMEs and onboarding guides; the evidence is all image-review work. Adding a worked example from ops or API docs is the obvious next edit.
• It has no advice for testing under the conditions of real use — a tired reader at 3am on a phone mid-incident. It names this as a blind spot and stops there, which is honest but thin for runbooks specifically.
• It cannot test discovery or truth, by construction. The reader is handed the file, and a reader who confidently applies wrong advice writes a confident answer. Both are named in the file with what covers them instead.
• The bluntness framing may lose force as it becomes routine. The findings in later rounds were noticeably gentler than in the first, which may be the document improving or may be the method wearing out. There is no way to tell from inside it.