compact-docs-writer

Compact docs writer

Rewrite a doc — or draft a new one — for token economy: carry all its rules and intent in the least text possible, because the doc loads into agent context and is paid for on every read. Then prove nothing was lost: present the change with a word delta measured from the files, and apply only on approval.

Core principle

Write each piece of information with the least text that still preserves every rule, constraint, edge case, and intent. Two directions, equally binding:

• Cut duplication, filler, and anything restatable more briefly.
• Never drop text whose removal loses information or instruction, just to be shorter.

Recurring reflex: "Can this exact rule be said in fewer words?" — if yes, do it.

The no-op test licenses one more deletion. Ask of each sentence, in isolation: "does it change the agent's behaviour versus its default?" If not, it's a no-op — the agent already acts this way, so removing it loses nothing: delete the whole sentence rather than trimming words from it.

Compaction counts words and information density, not whitespace. Blank lines between distinct chunks cost effectively nothing and aid the human reader, so keep them where they help; never collapse a long passage into one dense block to look shorter. The same economy runs both ways: a human-readability gain that is free or near-free in tokens — a blank line, a line break, a semicolon-chained enumeration rendered as a bullet list — is always applied, never skipped to look compact.

Structure follows the same economy: co-locate a concept — its rule, exceptions, and caveats under one heading, never scattered — so a reader who jumps to one part gets the others with it.

Leading words

When one concept keeps getting restated, collapse it into a single leading word the model already carries from pretraining, and reuse that word wherever the concept applies: it anchors the same behaviour in one token and reads sharper than any paraphrase. The collapse still obeys the core principle — the word must carry every constraint it replaces, and whatever it doesn't carry stays spelled out: "fast, low-overhead feedback" collapses into a tight loop, but a "deterministic" requirement isn't inside tight, so it survives as its own word. Hunt for these collapses in every pass.