/cold-reader

name: cold-reader
description: "A document is done when a reader with no project context can understand it; this skill runs that check as a Vale lint plus a context-free reviewer pass and a scorecard. This skill SHOULD be used when reviewing, finalizing, or being asked to critique a persisted project document: a spec, blueprint, RFC, ADR, design or discovery document, research or solution document, proposal, planning doc, runbook, README, or Jira ticket. It SHOULD also be used when the user asks whether a document makes sense to someone new, or asks for a jargon or clarity check. Do NOT invoke while a draft is still being written; the human-writing skill invokes this skill once a persisted project document draft is complete. Do NOT use on Slack messages, emails, code review comments, commit messages, pull request descriptions, or any text that is not a persisted document."

Cold Reader

A document is done when a reader with no project context can understand it. This skill checks that in two stages. A Vale lint catches the defect families a fresh reader resolves without friction and therefore never reports as confusing: change narration, evidence narration, and unattributed-source claims, plus light checks for bare ticket codes and agentless decisions ("it was decided"). A cold-reader review then catches the defects that need judgment: coined terms, producer-side names, methodology worksheets, identifiers standing in for vocabulary, claims with no actor, and generic or placeholder nouns used where a specific name exists. The lint runs first because it is cheap and deterministic, and it targets exactly the families the cold reader is known to miss. The two stages overlap on purpose at the edges: the cold reader is also asked for change and evidence narration and for claims with no actor, which the lint matches too, because the lint only hits fixed phrasings and a semantic variant slips past it. Deduplicate when you combine the outputs, keeping the lint's location and the reader's reasoning.

This is a comprehension gate and nothing else. It does not judge tone, vocabulary, or house style, and it can pass a document that the writing standard would fail: every repair that resolves a defect by explaining it makes the document longer, and running this skill to a clean result on its own tends to inflate a document. Pair it with the prose-style guidance in the human-writing skill, which pushes the other way, and read step 7's repair order as the place the two meet.

The skill takes no audience argument. Stage 2 sends the reviewer the brief and the document and nothing else, so an audience supplied at invocation has nowhere to go, and reader knowledge injected into stage 2 would stop it being a cold read. An audience matters at triage in step 6, where a term standard for the document's stated readership can be discarded, and it can inform a second opinion after the cold read finishes. It never reaches the reviewer.

Use it on project documentation: specs, RFCs, ADRs, design docs, discovery and solution documents, proposals, and READMEs for new tools. Do not use it on chat messages or emails or ephemeral documents that won't be persisted.

Stage 1: lint

1. **Run the lint.** The config ships with this skill. Run:

   vale --config="${CLAUDE_SKILL_DIR}/assets/.vale.ini" --output=JSON "<document.md>"

The config lints `.md`, `.markdown`, and `.txt` files. Vale skips any other extension and reports `{}`, which looks like a clean pass, so copy a document in another format (a `.rst` or `.adoc` file, a ticket body pasted into the conversation) to a temporary `.md` file and lint the copy. If `${CLAUDE_SKILL_DIR}` is unset, resolve `assets/.vale.ini` relative to this SKILL.md's directory.

If the `vale` binary is missing, stop and tell the user to install it with `brew install vale` (or see <https://vale.sh/docs/install>). Do not substitute a hand-rolled grep pass; the rule set only runs under Vale. JSON output maps each file to a list of alerts with `Check` (rule name), `Line`, `Span`, `Match`, `Message`, and `Severity`.

2. **Triage every alert.** The rules are precise but not perfect. Waive an alert when:

• the match is a literal technical sense (an HTTP request payload, a physical envelope, "the appropriate values" where the values are named on the spot);
• the match sits inside a verbatim quotation, code block content Vale missed, or text the document must preserve exactly;
• the match is a platform-required form ("Fixes #123" in a PR body);
• the history or evidence IS the document's subject (a migration guide saying "clients previously authenticated with API keys", a discovery document reporting what its own testing found);
• an identifier-shaped term is real vocabulary (a product code like ABC-123); add it to the rule's `exceptions` list so the waiver persists.

Severity sets the default: warnings expect this judgment call, suggestions are pointers. Every waiver needs a stated reason. Do not waive an alert only because the phrasing sounds fine to you; each rule marks a defect family the cold reader cannot catch, so an unwaived match is the only signal you get for it.

3. **Fix, then re-run.** For a document you are writing: fix every standing alert and re-run until Vale reports none, then move to stage 2. For someone else's document: keep the standing alerts for the combined report and move to stage 2.

Stage 2: cold read and report

4. **Send the document to a cold reviewer.** Spawn one fresh subagent (for Claude Code, the Task/Agent tool with a general-purpose agent). Its prompt is [`references/reviewer-brief.md`](references/reviewer-brief.md) from the horizontal rule down, verbatim, then a separator line, then the complete document text. The lines above that rule are notes to you, including the brief's version number, and they do not go to the reviewer. Nothing else: no file paths, no project summary, no explanation of what the document