kevmoo/kevmoo_skills/cold-read

Cold Read (/cold-read)

A cold read answers one question about a draft: can the intended reader make their next decision from the first N lines, and what would they cut?

The reader runs in a fresh context. It must not see the conversation that produced the draft. That conversation is exactly what leaks into agent-written artifacts as process narration and as background the reader already has.

Invocation

/cold-read <path> [--role triager|owner|reviewer] [--n 3]

• path: the draft file, in the form a human will see it. Strip draft-only

preview lines first; a leading # <Proposed Title> line stays and counts as line 1.

• --role: who reads it. Default triager. Use owner when the likely reader

is you or a single maintainer of your own package (<your_user>/*). Use triager for issues filed against external teams or multi-maintainer repositories. Use reviewer for pull request bodies.

• --n: lines the reader gets before it must decide. Default 3.

Steps

1. Resolve the role. Without --role, infer it: owner when the target is

your own repository (<your_user>/*) or a single-author internal package; triager for issues/bugs filed against external teams or multi-author repositories (even if one maintainer recently touched the referenced file). Pull request bodies default to reviewer.

1. Spawn a fresh-context, tool-restricted read-only reader. Define or select

a strictly read-only subagent (EnableWriteTools: false or a read-only Explore / research agent with file-read access only and no shell execution—never an unrestricted general self subagent, so flash cannot shell out to python3 or wc for words_above_fold). Give it only three inputs: the contents of references/persona.md, the role and N, and the draft file path—nothing else from the current conversation.

1. Require the JSON shape in

references/schema.json. Re-run once if the reply is prose. Recompute verdict from decision_line and N yourself; the model's decision_line is the signal, its verdict is a convenience.

1. Act on the verdict.

• decide_in_n: proceed.
• decide_later or cannot_decide: move the sentence that carries the

decision to the first body line, apply cut_list (keeping any sections required by the repository's PR template), add any missing facts, then re-run once. On issues and bug reports, the first body line must state the user/agent problem and observable symptom—never hoist a prescriptive implementation proposal (`"Add X to file Y"`) to line 1; keep fix ideas at the bottom under a non-prescriptive `Possible directions` or `Proposed Fix` section.

1. Report one line in chat: verdict, decision line, words above the fold,

and the number of cut lines. Do not restate the draft.

Model choice

A fast model (flash) is sufficient for single-draft gating once references/persona.md anchors decision_line to the first line of the block; both flash and the default model score the regression fixtures identically. For batch baselines over multi-section artifacts, prefer the default model when quota allows: in a 10-artifact calibration sample, flash placed decision_line earlier on 2 of 10 drafts.

Batch mode

For baselines over many past artifacts, run one reader per artifact in parallel, each in its own fresh context, and tabulate verdict, decision_line, words_above_fold, the known_to_reader count, and missing. Never give one reader two artifacts; the second read is primed by the first.

What the reader is for

The reader enforces the five outbound authoring principles and targets three failure modes of agent-written text:

<!-- BEGIN SPOT: workflow-outbound-five-principles -->

1. Lead with the decision. Line 1 states the defect, ask, or change.

Discovery history and process narrative go last or in a collapsed block.

1. Budget words by reader count. Title: hundreds of readers, search key +

decision signal, <= 70 chars. First 3 lines: tens, enough to triage or review. Body: one reader, repro + evidence + permalinks.

1. Report the delta, not the tour. Open with what is wrong or what changes.

The owner already knows how their code works today, so a "currently, X does Y" opener is cut; a visitor gets one orienting line + permalink.

1. Fill a slot only if it changes a decision. Delete empty template

sections, headers over single paragraphs, and parenthetical asides. One audience and one owner per artifact.

1. Anchor, verify, then cold-read. In issues/bugs, every claim carries a

permalink and repro/verification steps. In PRs and code reviews, never narrate the diff file-by-file or recite routine CI checks (dart analyze/ dart test)—state only the intent/why, non-obvious callouts or breaking changes, Fixes #N, and non-CI verification (e.g. benchmarks or manual UI checks). Traces go in <details> or issue attachments. Run /cold-read on the publish form and fix anything the reader cannot decide from the first 3 lines.

<!-- END SPOT: workflow-outbound-five-principles -->

• Discovery narration: leading with what the agent found, in the order it

found it.

• Background the reader already has: a tour of the reader's own code,

including a "currently, X does Y" opener.

• Template slots filled for completeness rather than for a decision.

It does not judge style, tone, or grammar.