cold_read.md

name	cold-read
description	Two-pass cold-reader review of a written work — paper, book, whitepaper, design doc, spec, or a code repo's README/docs — simulating a fresh reader. Auto-locates the primary artifact to review, tracks observations across two passes, and reports a synthesized punch list. Accepts optional focus arguments.

Cold Read

Perform a thorough cold-reader review of a repository's primary written artifact, simulating a fresh reader encountering it for the first time, and report back with substantive observations.

Strict process rules

These are non-negotiable; the value of a cold read comes from this structure.

1. You do the reading yourself. Do NOT delegate to sub-agents or use the Agent tool to read sections in parallel. Cold-reading depends on a single consciousness encountering the prose linearly; sub-agents fragment the read and lose the cumulative-impression work the method depends on.
2. Read the whole artifact, linearly, in order. Do not skip sections, do not skim, do not read only what changed since some prior conversation.
3. Do two full passes. Pass 1, an internal review of accumulated observations, then Pass 2, then a final synthesis. Not one careful pass — two distinct passes.

Finding what to read

Before reading, identify the primary artifact the cold read should target: the thing a fresh reader is meant to encounter and judge, not the build tooling around it. Use judgment based on what the repo actually contains.

Priority, highest first:

1. A paper or whitepaper. A single-document argument: a main.tex / paper.tex / *.typ, a paper.md / whitepaper.md / a README that is the paper, a paper/ or docs/paper/ directory, an arXiv-style source, or a built *.pdf with source beside it. Review the whole paper.
2. A book or long-form manuscript. A multi-file prose work with a build entry point — a main.tex/book.tex that \includes chapters, an mdBook SUMMARY.md, a manuscript/, book/, chapters/, or prose src/. Read it in reading order, taken from the entry/build file.
3. A design doc, spec, RFC, or substantial documentation set. If the repo's center of gravity is a design document, specification, ARCHITECTURE.md, RFC, or a docs site (docs/, mkdocs.yml, a Docusaurus/Sphinx tree), review that prose.
4. A code-only repository. When there is no prose artifact, the artifact is the README plus the documentation surface: the top-level README first, then the key doc comments (module/package headers, public-API and class/function docstrings), and any docs/ or design notes. A cold read of code reviews how the project reads and explains itself to a newcomer — clarity, onboarding, conceptual coherence, gaps in explanation — not the correctness of the code logic. Say so in the report so the user knows what was and was not reviewed.

Reading order:

• If a build or entry file exists (main.tex, book.tex, SUMMARY.md, mkdocs.yml, an index.*, a table of contents), take the reading order from it — it is the source of truth, and hand-built file lists drift.
• Otherwise infer the intended order from numbered files/chapters, a table of contents, or README links.

Read the source files directly (.tex / .md / source), not only a rendered or built output, so you can cite exact file:line locations. Fall back to a rendered or plain-text build only if the source is unavailable or unreadable.

If several artifacts are plausible (e.g., both a paper and extensive docs) or none is clearly primary, state which you chose and why at the top of the report. If the choice is genuinely ambiguous and would change the whole review, ask the user before reading.

Process

Pass 1: Initial cold read

Read the whole artifact linearly. As you go, keep an internal running list of observations; don't try to resolve them, just note them. Worth tracking:

• Questions that come up and aren't answered
• Places where the prose is doing less work than it should
• Forward-references that don't resolve, or take too long to
• Factual or technical claims that smell wrong or need verification
• Argumentative or explanatory gaps where a claim could use more grounding
• Cumulative-weight issues (closing weight, terminology load, example/illustration density, register shifts)
• Structural redundancy across sections
• Voice/register inconsistencies
• Sections that read as load-bearing vs. decorative
• Things that strike you as genuinely good — specific phrasings, structural moves, examples that earn their place
• Anywhere the author seems to be reaching too hard or overselling
• Pace and momentum across section/chapter transitions
• (For docs/code) onboarding friction: could a newcomer actually follow this; what is assumed but never explained

Internal review (after Pass 1)

Sort your accumulated observations:

• Items that have answers later in the text (mark for re-evaluation in Pass 2)
• Items that are real structural concerns
• Items that are stylistic preferences vs. structural issues
• Items where you're unsure (mark for re-evaluation)

Pass 2: Second cold read

Read the whole artifact again, fresh. As you go:

• Confirm Pass-1 items that hold up
• Drop items that turned out to be Pass-1 artifacts
• Add items that only became visible on second read
• Notice what reads differently the second time (a section lands harder; one that seemed important now seems decorative)

Final synthesis

After Pass 2: confirm the items that survived both passes, integrate anything newly visible, and silently drop items that resolved on re-read. Resolved items just disappear from the final list — they are not reported as their own section. Then report to the user.

Why two passes (methodology, not just thoroughness)

The first-pass → internal-review → second-pass pattern separates first-impression noise from structural signal:

• Pass 1 produces raw impressions, including artifacts: things that confuse you only because you haven't yet hit the resolution, things that seem missing only because you missed the section that handled them, things that seem important only because they're new to you.
• The internal review sorts impressions by likelihood of holding up; some resolve once you think about what came later.
• Pass 2 tests which impressions survive re-encounter. Items that survive both passes are high-confidence; items added in Pass 2 only became visible with the whole picture in view; items dropped were Pass-1 artifacts.

A single careful pass produces noisier output, because it cannot distinguish first-impression artifacts from real concerns. Preserve the two-pass structure even when it feels redundant; the redundancy is doing the signal-extraction work.

Honesty: calibrated in both directions

This is a polish-phase review. The user wants HONEST feedback calibrated in both directions; neither manufactured criticism nor empty praise is signal.

On flagging issues:

• Flag real concerns; don't bury your actual read under hedges.
• Do NOT manufacture criticism to seem rigorous. If something works, don't invent problems with it.
• Test for flagging: "Would addressing this be worth the cost?" If no, don't flag it.
• Don't nitpick. Cold reads target structural, argumentative, or cumulative-weight issues at the section / whole-work level, not cosmetics.

On naming what's working:

• Genuine positive observations are signal, not flattery. If a move lands, a phrasing is sharp, an argument does surprising work, an example earns its place — say so, and say WHY.
• Test for a positive: "Is this a true structural observation a thoughtful reader would make?" If yes, include it.
• Avoid generic praise ("this section is good") and empty hedges ("interesting"). Specific observations only.
• Flattery and manufactured criticism are symmetric failure modes; apply the same bar to both.

A report that says "the work is in strong shape; here are four things that land well and two calibration questions you can decide" is a valid, useful outcome if that is what the reading produced.

Output format

Roughly:

1. Brief overall impression (3–4 sentences). Where the work sits, what's most distinctive about its current state. Note here which artifact you reviewed, and — for a code repo — that the read covered the docs/prose surface, not code correctness.
2. What stands out as working. Lead with genuine strengths; be specific (name sections, moves, phrasings). No generic praise.
3. Substantive observations / actionable items. Things that genuinely matter and would improve the work. Cite locations as file:line markdown links, e.g. [src/intro.md:42](src/intro.md#L42). For each, briefly say what would address it.
4. Stylistic calibration questions. Concerns that are the author's call; frame as questions, not directives.
5. Net summary. Where the work stands, whether the remaining items are substantive or editorial, and what a next pass should focus on (if any).

Do NOT include an "items resolved on second read" section — Pass-1 artifacts are dropped silently. Keep the report tight; the user can ask for elaboration.

Respect the project's own conventions

Before flagging style or structure, check for project conventions — CLAUDE.md, CONTRIBUTING, a style guide, .editorconfig, or simply the dominant pattern in the existing files. Don't flag the work for following its own documented conventions, and don't recommend violating them. If a convention genuinely seems to hurt the reader, raise it as a calibration question, not a defect.

Optional focus

If invoked with arguments (e.g., /cold-read with focus on the introduction or /cold-read with particular attention to onboarding), prioritize that focus in both passes without skipping the rest.

Examples:

• /cold-read with focus on <section> — read everything, scrutinize that part harder
• /cold-read with focus on prose quality — flag stylistic issues more aggressively
• /cold-read with focus on argumentative gaps — hunt for under-grounded claims
• /cold-read with focus on accessibility for <audience> — check whether jargon and structure work for that reader
• /cold-read with focus on onboarding — for docs/code, whether a newcomer can actually get started
• /cold-read with focus on factual accuracy — verify claims (may need WebSearch / fact-checking)

The focus modifies emphasis, not coverage. You still read everything, twice.

Things to flag, things not to flag

Worth flagging: prose doing less work than it could; forward-references that don't resolve; cumulative-weight issues; claims that need verification; structural redundancy; voice/register inconsistency; argumentative or explanatory gaps; high-leverage tightening opportunities; reaching/overselling; a strong move that a one-line synthesis would sharpen; (for docs) unexplained assumptions and onboarding friction.

Not worth flagging: cosmetic typos/punctuation (other passes and linters catch these); generic "could be expanded" suggestions unless the expansion is load-bearing; vague "this is good" praise; stylistic preferences dressed up as structural concerns.

What to do if the work is in genuinely good shape

If both passes confirm it's solid with no substantive issues left, say so plainly: "The work is in strong shape; remaining items are editorial calls, not substantive concerns," then list the editorial calls briefly. A "good shape" report is a valid, useful outcome when it's earned by the actual reading rather than offered as flattery.