The editor for context architecture

See what your AI project forgot to explain.

Cold Read reviews the files that tell an AI how to work—like CLAUDE.md, CONTEXT.md, examples, and reference material. It finds what is missing, contradictory, vague, or stuck in your head, then hands the decisions back to you.

See a critique Download v0.1.2

Open source · MIT licensed · Created by Jude Doocey

Review memo · Full Review

Your system works because you remember what the files do not.

Missing approvalA client charge can happen without a person authorising it.

Conflicting rulesOne file requires sign-off; another sends automatically.

Vague completion test“Solid enough” gives no one a checkable finish line.

The difference

Cold Read is an editor. Not a rewriter.

It points at the exact weak line, explains what happens because of it, and tells you which decision still needs to be made. It will not replace your file, write your prompt, or quietly become the author of your work.

What it checks

Problems that only appear when someone else tries to use it.

Cold Read judges each project against what that project is actually trying to do. It does not demand more files, agents, or process unless the work genuinely earns them.

Missing responsibility

An important job, approval, or connecting step exists in the workflow—but nothing owns it.

Contradictory instructions

Two files tell the AI to behave differently at the same moment, leaving the outcome to chance.

Unobservable rules

Words like “good,” “appropriate,” or “solid enough” sound useful but give no one a finish line they can check.

Knowledge stuck in your head

The project works for its builder, but a stranger or fresh session would not know how to continue.

Unnecessary complexity

Extra agents, duplicated rules, or reference files add cost without improving the work.

Working demonstration

Inspect the project. Follow the evidence. Change the review depth.

This fictional client-onboarding project contains seven relevant files and eight distinct material findings. Use the file explorer and evidence links like a real editor, then compare the two complete review contracts.

Quick

Complete inventory, five priorities detailed.

Cold Read inspects the whole relevant project, fully reports the five most consequential findings, and discloses anything remaining.

Full

Every material finding, no fixed cap.

The same project and inventory, with all eight findings detailed plus the complete architecture and handoff assessment.

client-onboarding — Cold Read workspace

CLAUDE.md

Quick Review

5 priorities detailed · 3 remaining findings disclosed

Revision required

8 total findings 7 relevant files inspected 0 exclusions evidence complete

F01CriticalContradiction

Client sign-off conflicts with automatic delivery.

Why it fails: the root requires sign-off while the delivery contract sends as soon as it decides the summary is ready.

Consequence: client-facing work can leave without the promised human approval.

Builder decision: decide which surface owns sending and whether approval is mandatory before that action.

F02CriticalMissing responsibility

Payment has no human approval point.

Why it fails: the project authorises a consequential financial action, but none of the seven relevant files assigns responsibility for approving it.

Consequence: a delivery decision can trigger a client charge without a person checking that it is valid.

Builder decision: decide what must be true, and who must agree, before money is allowed to move.

F03HighHandoff gap

Research does not produce a recognisable delivery input.

Why it fails: research says to save notes and pass a brief, but no accessible rule identifies the canonical artifact that delivery should recognise.

Consequence: a fresh session cannot tell which output is complete, current, or safe to continue from.

Builder decision: decide what information must cross the stage boundary and how the next task recognises it.

F04HighUnobservable rule

“Solid enough” gives research no checkable finish line.

Why it fails: nothing ties the phrase to required evidence, coverage, or a decision the research must support.

Consequence: two sessions can stop at different points and both claim to have followed the workflow.

Builder decision: define what someone must be able to observe before research is complete.

F05HighUnobservable rule

The missing-data fallback is “use your judgment and continue.”

Why it fails: the fallback gives no boundary for when uncertainty is acceptable, disclosed, or escalated.

Consequence: unsupported market claims can flow into a client deliverable as if they were verified.

Builder decision: decide how uncertainty changes the output and when the workflow must stop or ask.

F06MediumContradiction

Two files assign incompatible client tones.

Why it fails: the root demands neutral language while the dedicated reference demands warm, conversational language.

Consequence: client voice depends on whichever file a session treats as authoritative.

Builder decision: choose one canonical owner for tone and resolve the incompatible direction.

F07MediumDuplicated ownership

Run state is deliberately maintained in two root files.

Why it fails: both files own the same current-stage and next-action responsibility, so neither is canonical.

Consequence: one update can leave two plausible but different answers about where work should resume.

Builder decision: decide which single surface owns resumable state and what the other is for, if anything.

F08MediumUnproven behavior

The project claims it never sends an incomplete summary, but shows no proof.

Why it fails: this is a material “never” guarantee on client-facing behavior, yet the supplied project contains no example or test exercising the block.

Consequence: a reader cannot distinguish an enforced boundary from a sentence the workflow may ignore.

Builder decision: demonstrate the claimed refusal against an incomplete input before relying on it.

Remaining inventory — disclosed, not hidden

Quick Review stops full detail at five priorities. These three findings still belong to the same complete inventory.

F06Conflicting client-tone authorityMedium · Contradiction

F07Run state owned in two filesMedium · Duplicated ownership

F08Incomplete-summary block is unprovenMedium · Unproven behavior

Full Review only

Complete architecture assessment

Necessity read

One root guide, three workflow contracts, and one shared tone reference are proportionate for this job. The project does not earn multiple agents. The second state file is excess rather than useful separation.

Ownership, routing, and handoff

Sending is governed by conflicting owners; payment approval is unowned; research-to-delivery continuity relies on an unnamed artifact; and resumable state has two owners. The missing architecture is decisions and canonical signals—not another agent.

Prioritised action plan

Settle human authority over client sending and payment.
Make the research-to-delivery handoff recognisable to a fresh session.
Give research completion and uncertainty observable boundaries.
Choose canonical owners for tone and resumable state.
Demonstrate the claimed incomplete-summary refusal.

Next test

Open the project in a fresh session halfway through a run. Using only these files, ask it to identify the current stage, locate the accepted research input, decide whether sending is authorised, and explain whether billing may proceed. Then test an incomplete summary to see whether delivery actually stops.

Cold Read · read onlyQuick · 5 detailed / 8 total

CLAUDE.md7 files inspected

Illustrative project-editor demonstration. The eight findings are complete for this fictional seven-file example; this is not a live AI response.

Boundary demonstration

Not every folder is an AI system.

Cold Read is for folder-based AI systems, including ICM projects. When an ordinary engineering folder has no root instructions, AI purpose, routing, or context layer, it stops instead of inventing an architecture to criticise.

engineering-notes — Cold Read scope check

No review mode requested

Scope check

0 findings · stopped before architecture judgments

Out of scope

5 files inspected 0 AI instruction files 0 findings produced

No AI-operating intent is present.

There is no root instruction file, no CLAUDE.md, no routing or context layer, no stated purpose, and nothing in the tree that establishes an AI-operating intent.

This is a folder of engineering content, not a folder-based AI system. Cold Read reviews the architecture that turns a folder into an AI-run system: routing, ownership, rules, gates, and handoffs.

With no instruction layer present at all, there is no relevant architecture to inspect. Applying those judgments to a document and code repository would invent an architecture that is not there.

What Cold Read does next Stops. No Quick/Full question. No fabricated findings.

An ordinary folder is not marked as badly designed just because it was never intended to operate an AI specialist.

Cold Read · read onlyOut of scope · terminal state

engineering-notesNo AI system detected

Illustrative boundary example based on an observed Cold Read response. No files are modified.

Folders as architecture

Five parts. One job each.

The editor follows the competition methodology exactly. No adapter file, hidden setup, or extra agent layer.

identity.md

Who Cold Read is, what it reviews, and where it stops.

rules.md

The canonical critique procedure and output contract.

examples.md

Worked demonstrations of specific, bounded critique.

reference/

Architecture judgments, finding labels, and severity guidance.

README.md

How a stranger installs the editor and hands it a project.

Use it

Two simple ways to start.

Claude Code · no download

Open your project. Paste this prompt.

Claude Code loads Cold Read for the current session.

The open folder is the AI project I want reviewed.

Clone Cold Read from https://github.com/DooceyBoy/cold-read into a temporary folder outside my project. Use all six Markdown files inside cold-read/ as the review instructions, with rules.md as final authority.

Do not copy anything into, edit, or rewrite my project. Ask whether I want a Quick Review or Full Review.

Approve GitHub access if asked, then choose Quick Review or Full Review.

Using Claude Projects? Follow the three steps below.

Step 01

Add Cold Read to a Claude Project.

Upload the complete six-file editor folder as Project knowledge.

Step 02

Copy your project. Keep its normal name.

Do not rename it or place it inside Cold Read. Attach or paste it with its folder tree and paths intact.

Step 03

Ask for a Quick or Full Review.

Quick details five priorities and discloses the rest of the complete inventory. Full details every material finding with no fixed cap.

Cold Read does

“This line leaves approval unowned.”

It identifies the exact place, consequence, missing decision, and—when earned—the conceptual shape a revision needs.

Cold Read does not

“Here is your corrected file.”

No replacement wording. No ready-to-paste prompt. No finished folder structure. The builder keeps the pen.

Give your project one cold read before someone else does.

Download the editor, add it to a Claude Project, and see whether your context can travel without you.

Download Cold Read Read the GitHub guide

Cold Read v0.1.2 is the finished public version and is open source under the MIT License. Its public evidence summaries record checks completed during development; they are supporting records, not alternate editions or demo downloads.