/editorial-pass

name: editorial-pass
description: Review a finished or near-finished document the way a human editor reads it, start to finish, building a model of what it's trying to communicate, then diagnosing cohesion, coherence, narrative throughline, pacing, consistency, reading fluency, contextualization, and clarity across the whole piece, never just line-by-line. Also hunts four noise categories agents habitually leave behind: provenance narration ("as verified in X", "so-and-so confirmed"), ruled-out-hypothesis residue ("we confirmed it is not Y"), self-referential scaffolding, and dramatized background (illustrating known concepts, stakes-selling, deriving what only needs asserting). Use whenever the user asks to review, edit, polish, tighten, or clean up a document, asks whether a doc "reads well", "flows", "makes sense", or "has a throughline", or before shipping any long-form prose another human will read: TDDs, RCAs, design docs, investigation writeups, READMEs, proposals, long PR descriptions.

Editorial pass

Agents review documents the way linters review code: one localized finding at a time, each judged against a rule, none judged against the whole. A human editor does something different. They read the document start to finish, build a running model of what it is trying to tell them, notice where that model gets confused or bored or lost, and only then descend to the line level. Most of what makes a document fail is invisible at the line level: a section that answers a question nobody has asked yet, a term that changes meaning halfway through, a middle that sags because three paragraphs repeat one idea, an ending that pays off a promise the opening never made.

This skill is that editor. It applies to any long-form document, technical or not. Do not treat a TDD and an essay as different species: humans process both through well-sequenced steps, stakes, and payoffs. It is all storytelling, and the editor's job is the same everywhere: minimize the reader's risk and mental load in getting what the document is trying to communicate. For a technical doc that means the reader can answer *what are we solving, why, and how* without rereading.

One boundary before anything else: this is a prose editor, not a technical reviewer. You review the writing, never the work the writing describes. Whether the schema is right, the design is sound, or the numbers hold is someone else's review; your jurisdiction is whether a reader can receive what the document says. The one exception is *internal* contradiction: when the document disagrees with itself, that is a writing defect and yours to flag.

When to invoke

Whenever a document exists and a human is going to read it: the user asks for a review, an edit, a polish, a "does this make sense" check, or a cleanup of a draft you or someone else produced. Invoke proactively after you finish drafting any long-form document, because the failure modes below are precisely the ones drafting agents introduce. For *writing* a document from scratch, `/flagrare:write-docs` owns the craft and `/flagrare:tdd-writer` owns TDDs; this skill is the read-and-repair counterpart and assumes a draft already exists.

The contract: produce the editorial memo first (step 5), get the author's go-ahead, then apply. Do not silently rewrite someone's document as step one.

The procedure

1. Read the whole document. Twice.

Read the full document before writing a single note. The first read is for the felt experience, as the target reader, not as a reviewer: where did you lean in, where did attention drift, where did you have to backtrack and reread, what did you have to hold in your head unresolved and for how long. Resist the impulse to annotate on first contact. Many apparent problems resolve later in the document, and many real problems only become visible in retrospect.

When the first read ends, write one sentence: *what is this document trying to communicate?* That sentence is the spine. Everything else in the review hangs off it. If you cannot write the sentence, that inability is the primary finding and nothing at the line level matters yet.

The second read is diagnostic. Now you know what the document is trying to do, so the question becomes: where does it succeed at that, and where does it fall short?

2. Diagnose from large to small

Structure before flow, flow before paragraphs, paragraphs before lines. An editorial memo that opens with comma splices when the document has a broken arc wastes the author's attention. Work down through four layers:

**Throughline.** Does every section pay off the spine, or do some sections belong to a different document? Does the opening make a promise (a question, a stake, a hook) that the rest of the document keeps? Two cheap whole-document proxies: read only the headings in sequence and check whether a skim-reader could reconstruct the argument from them alone; then read only the first sentence of each paragraph and check whether they form a coherent chain on their own. Where either chain breaks, the structure is broken there, whatever the sentences say.

**Sequencing and contextualization.** A reader can only understand a sentence with what earlier sentences gave them. Walk the document asking, at each new concept, claim, or term: has the reader been given what they need to receive this, here? Context must land at the point of need, not in a glossary and not three sections late. The most common failure is curse-of-knowledge ordering: the author presents things in the order they learned them, or the order the system executes them, instead of the order a stranger can absorb them.

**Pacing and proportion.** Space in a document is emphasis. Does the amount of text each idea gets match its importance to the spine? The two standard failures are opposites: the load-bearing risk compressed into one six-clause sentence, and a minor mechanism sprawled across three paragraphs because the author found it interesting to fig