Message test: measure what the reader actually took away

Instruments

Three tests, in order of what they cost you

Each one answers a narrower question than the last and costs more to run. Start at the top. Stop as soon as one of them sends you back to rewrite something.

• Clarity index

  A model · about 15 minutes · free

  Twenty items, one point each, scaled to 100. Is there a main message, and can you find it without hunting? Is there a stated action? Can the numbers be used? Does the risk come with a chance of happening?

  Pass at 90.

  0accepted band100

  Score zero whenever you are unsure. A model scoring a document it helped write drifts generous, so every point awarded has to arrive with the sentence that earned it.

  A pass means the known blockers are absent. It is not evidence that anyone understood anything.

• Reader test

  A model, kept isolated · minutes · nearly free

  Write down what a reader has to leave with. Hand the document, and nothing else, to a reader who has never seen it. Compare. Each point comes back landed, missing, or wrong.

  No threshold. Wrong answers outrank missing ones.

  A missing point is a gap. A wrong point is damage, because the document misled rather than merely failed.

  Then the part no metric produces: inventions, the things the reader came away believing that the document never said. Every one has a location, and that is where the fix goes.

  This measures extraction, not persuasion. Nobody has agreed to anything yet.

• Cloze test

  Four to six real readers · their afternoon

  Take 250 to 300 words of continuous prose from the part that carries the message. Delete every sixth word. Readers restore what they can, alone, without the original, with no clock running.

  Pass at 60 percent restored.

  0%accepted band100%

  Between 40 and 60 the text needs a briefing alongside it. Below 40 the audience cannot follow it unaided, so rewrite rather than tidy. Report the range too: one strong reader drags an average past 60 while the rest of the room is lost.

  The score belongs to that passage and those readers. It does not travel to the rest of the document.

Validity

Two ways a reader test quietly passes everything

Both failures produce a clean-looking report. Neither shows up in the number, so the run has to state which side of each rule it landed on.

• The reader was not actually fresh

  A subagent inherits the project’s CLAUDE.md and memory files. If those explain the subject, the reader answers half from the instructions and half from the document, and you cannot tell which half is which. It will wave through a document that carries no message of its own. Run the reader in a separate session outside the project, and make it say at the end what it already knew. Anything on that list contaminates the result.

• The answer key came from the document under test

  A key skimmed off the artifact asks whether the artifact repeats its own headlines. It always does, so that test cannot fail, and it cannot catch drift between a source document and the deck built from it. Take the key from the source, or from the author, before the test. Keep it in version control beside the artifact: a key edited after a bad result is not a test.

One run

How a run goes

One command works through four steps and stops at the first one that fails badly enough to make the rest pointless.

1. 1

   Prepare the artifact

   A PPTX, DOCX, ODP or ODT is rendered to PDF first. Slide order, what shares a slide, what got shrunk to a footnote: all of it carries message, and pulling the words out throws it away.

2. 2

   Name the reader, write the key

   Not “executives” but “a board member who has not read the source document and has eleven minutes.” Then three to five things they must leave with, each one markable right or wrong. If you cannot write that list, the document has no message yet.

3. 3

   Score the clarity index

   Failures worst first, each with the smallest edit that would pass it. Under 70 the run stops here. Structural problems drown out anything a reader could tell you, and fixing them costs less than measuring twice.

4. 4

   Send the reader in, then decide about the cloze

   Score what comes back against the key from step 2. A cloze test earns its cost only when the audience cannot ask questions and being misunderstood would be expensive.

# file · who the reader is · the source it was derived from
/message-test:run board-deck.pptx \
    "a board member with 11 minutes" \
    governance/the-source-document.md

Install

Install

Two lines in Claude Code. The plugin brings three skills and one command.

/plugin marketplace add cocodedk/message-test
/plugin install message-test@message-test

Apache-2.0. The cloze sheet builder and the text extractor are plain Python and need nothing beyond a standard install.

Provenance

Where the instruments come from

None of this was invented here. Two of the three are published instruments with published thresholds, which is the only reason the numbers can be compared to anything.

• ISO 24495-1:2023

  The plain language standard. It defines the target as a reader outcome, readers get what they need, can find it, understand it and use it, and it rejects readability formulas as the test of success.

  iso.org →

• CDC Clear Communication Index

  Twenty scored items out of 100, 90 to pass, about fifteen minutes. clarity-index adapts its seven published areas for general documents. When a score has to stand up formally, use the CDC score sheet itself and say which one you used.

  Score sheet, PDF →

• Cloze procedure · Taylor 1953

  Still the basis several readability formulas were calibrated against. The 60 percent threshold and the every-sixth-word interval follow the method as Nielsen Norman Group describes it.

  nngroup.com →