draft-marker-discipline

Draft Marker Discipline

Overview

A manuscript written across many sessions accumulates open questions. Where those questions live determines whether the draft is auditable or merely long.

Kept in chat, they evaporate at the end of the session. Kept in a separate issue list, they drift out of sync with the sentence they belong to. Kept in the source next to the claim, they survive, they travel with the text, and they can be counted.

This skill covers the marker system, the triage that makes a marker count meaningful, the measurement that makes a length claim honest, and the two mechanical traps that have each cost a real build.

When To Use

Use this skill when:

• a manuscript is drafted across sessions, by several people, or by agents
• you are about to do a batch pass over open markers
• you are about to quote the manuscript's length
• superseded material needs to be removed from the tree
• you are about to make the same edit across many files with a script

Do not use this skill for:

• deciding whether a claim's source supports it. That is claim-source-verification; this skill is the bookkeeping around it.
• restructuring an unstable argument. That is manuscript-optimizer.

1. Four Markers, Four Jobs

\TODO{...}        red     an unresolved FACTUAL or SOURCING question
\note{...}        blue    editorial, addressed to the authors
\directive{...}   boxed   what must change in this passage, and why
\superseded{...}  grey    text a freeze decision replaced, kept not deleted

All four vanish under a draft-mode switch, so a clean copy for circulation is one boolean away.

The discipline is the restriction on \TODO. It carries factual and sourcing questions only, never style notes, never "tighten this", never "consider rephrasing". Style goes in \note; a required change goes in \directive.

The payoff is that the \TODO count becomes a readiness metric rather than a mixed bag. "Thirty-seven open TODOs" means thirty-seven unresolved factual questions, which is a statement about the manuscript's evidentiary state. If style notes are mixed in, the number means nothing and stops being reported.