docgen

name

docgen

description

Owns all prose, markdown files and the comments inside source files and fences through a voice law, an anti-anchoring rule against rosters, counts, and freezes, a named defect catalog, file-kind templates, and a deterministic gate and fixer. Use when authoring, editing, or reviewing markdown of any kind and comments in source files; when designing a document schema or marker vocabulary; when pruning code comments; or on "clean up this doc", "tighten the prose", "this doc is stale".

[DOCGEN]

Write every sentence declarative and commanding, never explanatory: open on the imperative verb or the acting owner, state the action as law — prose tells its agent reader what to do, never explains behavior in the abstract. Sentences opening on an article — "A X is...", "The X provides...", and the hidden forms behind leaders: [<TOKEN>]: a …, <term>: the …, a table cell opening on an article — frame a definition that explains instead of commanding, and no determiner swap, deletion, or recasing repairs that frame: re-derive the fact the sentence carries and re-author it as the demand or owner-voice law. Every agent loading explanatory prose reproduces that voice in everything it writes next.

Instruction surfaces — skill, standard, template comment, prompt — command the writer in imperative demands; durable content states timeless owner-voice law. Write durable prose as law for an agent that loads it cold: every line changes that agent's next action or poisons it. Give every fact one owner and every line one decision.

Fix prose by silent removal, never by mutation in place: delete the defect whole and rebuild the passage to stand without it — no tombstone, no hedge, no never X minted for the cut. Author the replacement fresh from the fact the dead sentence carried; a partial edit keeps the broken frame under new words and leaves the passage illogical.

[01]-[ROUTING]

[REFERENCES]: Load before creating or editing prose:

• [01]-DEFECTS: defect classes — detection test and reframe per class

[TEMPLATES]: Start a new instance from its kind's template — copy the structure, fill the declared slots:

• [01]-IDEAS: Idea-card grammar at concept grain
• [02]-TASKLOG: Task-card grammar at landing grain
• [03]-README: Exact structure, slots only
• [04]-ARCHITECTURE: Exact structure, replace only the slots
• [05]-SPEC: Exact section spine, slots carry their budgets
• [06]-API_CATALOG: Exact structure, replace only the slots
• [07]-RULINGS: Permanent decision registry

[EXAMPLES]: Consult the matching symptom-indexed set before building or repairing the container:

• [01]-TABLES: Table crimes and their structural repairs
• [02]-LISTS: List crimes and their classified repairs
• [03]-MARKERS: Marker crimes and the declared-vocabulary repair
• [04]-INTROS: Leads that legislate and the rejected frames

[02]-[VOICE]

[OWNING_SUBJECT] — Seat the acting owner as the grammatical subject of every law sentence, under a present-active verb that exercises ownership: mints, owns, folds, routes, drives, binds, derives, admits, rejects. State the total positive claim that forecloses every alternative; a surface that merely supports, offers, or provides is not yet designed.

[PROHIBITION_BY_STRUCTURE] — Spell a forbidden form only where its enforcing mechanism is the subject of the same clause; state the one positive law that makes the negation redundant. State a negated contrast — not X but Y — as the Y claim alone; naming a forbidden form primes its emission.

[DECISION_PER_LINE] — State one resolved fact per line, timeless, with at most one load-bearing reason; strip reassurance, anticipated objections, ship-status, tags, and origin. Write a paragraph as one logical line — never hard-wrapped, never sentences stacked as pseudo-list lines.

[LOAD_BEARING_WORD] — Make every word earn its slot and write present active — an owner acts now, never was-acting, will-act, or is-acted-upon. Never trade capability for economy: split a two-decision entry into siblings, never write a longer line.

[ADDITIVE_REPAIR] — Repair additive filler shortest-first: delete the word and fold the tail into the clause or a serial list; then with carrying accompaniment; then FANBOYS and where a compound subject needs it; then a precise shorter word. Keep emphasis casing and the sense a quantity phrase carries.

[CAPABILITY] — State capability as present-tense owned fact with deep foresight; give an unmodelable capability silence. Reserve future tense for a card growth line and a research item carrying the exact question and its verification route.

[NAMED_SURFACE] — Write every nameable surface as a code span in its exact verified spelling; verify before authoring, and track an unverifiable member as an open item — the code span is the instruction, never a paraphrase.

[PROSE_CODE_BOUNDARY] — Name owners in prose, carry mechanism in code: at most the owning symbol as a code span with its law, while signatures, rosters, and per-member behavior live in the fence, catalog, or table tooling keeps true. Never fence what a catalog indexes. Write one decision per list entry — one owner, one charter phrase — demoting any tail, second clause, or mechanism aside.

[03]-[ADMISSION]

[REBUILD_TEST] — Admit a sentence only when it stays true across any doctrine-conforming rebuild: couple prose to intent — charter, invariant, boundary, ruling, trap — and let the fence own shape. Rosters, counts, seals, and litanies read as discipline and rot as law; state the extension rule — how one new row, case, or member lands — where the anchor stood. Pass a page only when a stronger fence body lands with zero prose edits.

[REGENERATION_TEST] — Delete the sentence; when a fresh agent regenerates the fact from disk and stated invariants, keep it deleted or demote it to a fence where structure must show. On an always-loaded surface, also delete every line the agent already obeys — retained rules dilute one another's pull. Regeneration rules out the mirror alone; a surviving fact still answers every defect class.

[ONE_OWNER] — Give every fact one prose owner — a second copy at any tier forks on first edit — and pick the owner by lifespan: the home outlives the fact, and relocation is a move, the losing surface stripped in the same pass. Interrogate every law sentence for who else binds it — the always-loaded chain, a sibling surface, a deterministic tool. Point with the owner and its one consumed symbol; compose doctrine silently downstream, never re-taught.

[04]-[TIER]

Land every fact at the lowest tier that owns it; hold the higher tier to the one invariant the fact instantiates. Move a sentence one tier down whenever the move loses no governing force over more than one child. Failure runs both ways: prose reaching below its tier freezes mechanism a rebuild must be free to re-derive, and prose floated above its tier dissolves into a platitude no rebuild can act on — delete any sentence whose deletion changes no rebuild.

• Corpus root: purpose, layer law, and entry routes by concern — never inventories of anything below.
• Area index: area invariants, unit-grain topology and boundaries, and admission law — never a unit's member roster or file names.
• Unit index: charter, fenced sub-structure, unit-grain seams, and owned registries — never wire byte-truth, signatures, or literals.
• Implementation page: mechanism, signatures, byte-truth, literals, and one owner's flow — never higher law restated or siblings re-taught.
• Work item: scoped intent, integration points, and growth pressure — never design content or settled law.
• In-code comment: one in-situ constraint the code cannot show — never anything else.

[DEMOTION] — Land the fact at its owner first, then collapse the higher copy to the invariant it instantiates; payload dropped during demotion is a defect.

[05]-[LEADS]

Engineer the lead, never accumulate it — first lines are the highest-value signal an agent loads.

• Hold a lead to one or two single-line paragraphs under 500 characters, opening on the document's own law — never doc-set, siblings, audience, or process.
• Demote a lead needing semicolons or parenthetical inventories — lower-tier payload; intro material earns its slot by changing the next action.

[06]-[SIGNAL_SELECTION]

Select what an index-tier page carries for one reader: the agent editing the unit in isolation.

• Carry closed signal bands, nothing else: the router, the registries the page owns, and the unit's boundary and refusal seams.
• Collapse provider inventories to registry cards, cross-owner consequences to seam rows, implementation mechanics to the owning page.
• Test every candidate sentence once: an agent landing here with no other context changes what it edits, admits, or refuses — or the line dies.
• Reject topology narration, sibling-role description, and provenance.
• Hold consistency over local optimality: a deviating index misplaced its extra — the shape is the contract, the extra goes to its owner.

[07]-[ROUTERS]

Routing is the one job that licenses linking and naming siblings; every other page composes settled law silently.

• Keep one router per corpus level, keyed by reader decision — one owning page per choice; a missing route is missing capability, a duplicate a fork.
• Scale a router by grouping: a unit spanning sub-folders groups cards under one [FOLDER_TOKEN]: label per folder, mirroring disk exactly; a small unit keeps one flat card list, and group labels are earned by the second folder, never decorative.
• Roster the routing license in the gate's ROUTING_FILES constant, never a grafted section; a relative link outside it fails as coupled-link.
• Write a route row as path, label, and one charter phrase — never signatures, member inventories, fault bands, or package decisions.
• Resolve every route in one hop: the charter phrase pitches what the target answers, and a target that only points onward is a dead route.
• Leave navigation below the route pointer to disk truth: the tree is the page index, and adding a leaf costs zero router edits.
• Never relink or re-teach siblings from a non-router page: mechanics at the owner, consequence at the consumer, the boundary fixed in one pointer line.
• Anchor a cross-owner reference on the target's public section token, extensionless and scope-qualified by distance; a .md path pins a file a move invalidates, and a lowercase anchor reaches a code symbol or slug the target renumbers away.

[08]-[EXAMPLE_CRAFT]

• Give each example one demonstration region no sibling example repeats.
• Show the form at real composed scale — admission, dispatch, and policy in one body, growth axis visible — never an isolated minimum.
• Ride diagram fences on the mermaid-diagramming skill for admission, type selection, construction, and render validation.
• Admit a diagram only as a declared regenerable representation whose fence carries structural payload only; the reader's renderer owns appearance.

[09]-[MARKER_SYSTEMS]

Keep many agents consistent inside one file class with a closed marker vocabulary riding a templated entry shape: the marker carries state, the schema carries structure, and prose carries only law.

• Declare the vocabulary once at the schema owner as a closed uppercase-bracketed token set — one meaning per token, greppable on the exact string.
• Compose entry leaders as [<ID>]-[<STATUS>]: so a lifecycle greps without parsing bodies; transition status by editing the leader, never in prose.
• Draw field lines under a leader from the closed field vocabulary in declared order; the schema splits required from optional-by-condition fields, and an optional field that decides nothing for this entry is omitted, never filled.
• Keep entry ids and their references UPPERCASE_SNAKE — a hyphenated slug anywhere is a defect — and every path corpus-relative, never an absolute machine path.
• Keep terminal marker sections past realization: a research or open-question section holds its header marker for the page's whole life, realizing a row deletes the row alone, and (none) marks the empty section — a deleted, displaced, duplicated, or deformed marker is a named defect.

[10]-[SCHEMA_OWNERSHIP]

Declare a file kind's schema once — ordered header set, entry shape with closed field vocabulary, marker vocabulary, sanctioned extension points — at the corpus standard nearest the kind; every instance and every instruction surface composes it silently.

• Conform every instance byte-structurally: identical header tokens, identical field sets per entry, zero undeclared markers — uniformity makes the corpus machine-censusable, and a locally-optimized deviation is a defect even when it reads better in isolation.
• Hold peer corpora to one spine: language swaps the fence tag, never sections, numbering pad, or card grammar; a branch skeleton is the same defect.
• Write the schema before writing another instance of a kind that cannot census.
• Land new capability as a row, entry, or declared extension in the schema; a new section is a schema change at the owner, rolled to every instance.
• Consolidate a vocabulary defined in two places to the owner and convert the second site to silence; scattered partial redefinitions rot a corpus.
• Compile the schema into tooling pressure — a census gate, a marker grep, a lint — and never let tooling invent vocabulary of its own.

[11]-[REWRITING]

Arm before reading: rebuilding an existing document is harder than writing fresh because the source's frame is the primary contaminant, and an agent that reads before arming itself inherits it. Hold these contamination modes through the whole pass:

• Re-derive every section set, emphasis, enumeration, and justification; unexamined, each becomes the rewrite's default.
• Judge a drifted page against corpus law and the sibling exemplar, never against itself — internally consistent reads as finished.
• Flip extracted authority to the corpus ruling; a source's deference rides its facts.
• Rebuild, never soften: a litany trimmed to three corpses or a chant shortened preserves the frame at lower volume.
• Re-derive hardest where source framing matches the first-draft instinct — the match is the anchor's strongest signal, never permission to proceed.

Run every pass touching an existing durable doc in this order:

1. Load the defect catalog, the voice, and the sibling exemplar of the target's kind; read the target as evidence.
2. Keep from the source only facts failing the regeneration test, mechanism whose owner sits here or lower, and open questions becoming tracked items.
3. Classify every suspect passage against the defect catalog before any fix; an unclassifiable passage is legal voice or a new class worth naming.
4. Author the new document from the exemplar's shape and the extracted payload; consult the source for payload completeness alone.
5. Move mechanism above its tier to its owner before the copy dies; split a compound of charter facet and mechanism first, never cut it whole.
6. Land both ends of every ripple in the same pass — seam counterpart, pointing consumer, registry row; re-scan every fold target for a minted twin.

[GROUNDED_REPAIR] — Parse a line to the subject and verb it carries and resolve every named surface at its owning catalog, fence, or manifest before touching it: compression built from the words alone inherits whatever the reader mis-parsed and ships that as law. Read the system a line governs until its claim proves out, and correct what that system refutes. Separate the two targets first — description repairs against the system's live truth, higher-order law holds its obligation whole whether or not any system yet honours it, and drift between them convicts the system.

[TABLE_REPAIR] — Repair a broken table through the moves examples/tables.md owns, never by flattening into prose or bare lists: decide eligibility first, repair in place, and convert a resisting row family last with index, label, and payload intact.

[LIST_REPAIR] — Classify fragments before cutting; fragment class, never length, selects the container: the law stays the bullet, mechanism moves to its fence, a sibling-governing consequence to the lead, a genuine exception to a contract qualifier on the law, and an entry whose fragments are all load-bearing at this tier promotes to a card with earned fields. Split entries answering different questions into separate containers.

[SPLIT_ADMISSION] — Admit a split only where each half stands alone: own subject, own antecedents, governing with its sibling absent. Hold one entry to at most two, each a decision the source already carried; fragments leaning on the line above, stranded relative clauses, and pronouns whose referent moved each name the failed split, repaired as one denser entry.

[BUDGET_REPAIR] — Spend the budget on law and cut explanation: excess rides as restated reason, narrated consequence, and roster, so delete those whole and leave every obligation, discriminant, and named owner at full strength. Keep one entry to one decision the source already carried, and let each surviving clause change the reader's next action. Refuse the cut reaching a number by shedding law — stranding a clause, inverting a claim, or reading as fluent nonsense lands worse than the line it replaced — and close by stating the residual beside its cost.

Exit only when the rewrite survives every test — the producer's grade admits, the cold read decides:

• Cold read: a fresh agent reading only the result cannot reconstruct the source's structure, emphasis, or history.
• Regeneration: every surviving sentence passes the regeneration test.
• Voice: every law sentence has an owning subject and verb — never a forbidden alternative, a consumer count, a process artifact, or the document itself.
• Mass: fewer lines than the source with zero payload lost — growth re-imported frame, and shrink that dropped mechanism destroyed capability.
• Integrity: every entry stands alone under its own subject and parses on one reading, and no surviving clause merely restates why a law holds.
• Demotions: every demotion target, reopened, still carries each demoted member and no wider set silently inherited as new law.

Treat a seal, ruling tag, or never-re-open clause as prose, not law — the rebuild mandate outranks self-declared immutability; true freezes live only outside the document — wire contracts at their codec owner, the corpus standards. Read length, density, and citation apparatus as effort, never correctness — a forty-line justification extracts to one policy row. Corpus law wins without negotiation; surface a conflict between corpus laws to the standards owner, never resolve it silently in-page.

[12]-[COMMENTS]

Write a comment only for the agent editing the file in isolation, in source and transcription-complete fences alike: one in-situ constraint the code cannot show, uncoupled from paths, sessions, and siblings, never duplicating card or index content. Delete a comment whose constraint the code carries, and prune stale comments every pass. Keep a machine-config comment naming its owning module's path; delete a narrating path.

Hold a block to the fewest lines that carry the constraint, each filled toward the 150-column cap; split a re-wrap asymmetrically — lead packed, tail carrying real width, never an even split. Refold an orphan line into a neighbor or rephrase it away. Gate counts bound the shape; header identity rows, shebangs, doc-comment glyphs, dividers, and tool pragmas never count, and the charter docstring is exempt only from the stack cap.

Run one ladder per comment: delete a no-load comment whole — narration, code restatement, a human-facing tour — keeping any real constraint it carried; tighten a load-bearing survivor in place, 3 lines to 2 and 2 to 1; then inline a one-line survivor governing one line as its trailing tail — short, atomic, positive, outside every count and width budget — while a block-governing comment stays above its block.

Rewrite on merge, never concatenate, and repair by read-and-rewrite judgment — the gate detects, no sed/regex mutates comment text. Correct dividers and docstring headers in style, structure, or label, never delete them; correct a phantom label only after reading the enclosing section.

[13]-[GATE]

Run the gate on every touched durable doc before returning. Run fix for the deterministic repairs its Repair vocabulary owns — dry-run prints the plan, --write mutates — and resolve every judgment-tier SKIP row by hand. Its Check vocabulary owns the mechanical census alone; a defect class the gate does not carry is review work against the catalog.

uv run scripts/prose_gate.py [--json] <paths...>

uv run scripts/prose_gate.py fix [--write] <paths...>

fix --write is the sole markdown formatter: every table expands, aligns, and pads to its canonical render there, never by hand. Gate and fixer share one table model, so a grid whose canonical render exceeds the width cap fails at any padding — that repair is structural, never re-padding. Card files and design-page [RESEARCH] sections census against the marker grammar their own source-only template comment declares.