Writer

Writer

writer is the directory and routing contract for academic and technical writing. It is intentionally compositional:

exactly one primary type + zero or more lenses + zero or more source objects

• zero or more domains + one format for artifacts (zero for chat-only prose)
• optional format integrations

The module selected for a task is the canonical home of that rule. Do not copy the same rule into a type, format integration, or reviewer.

For maintenance or feedback-driven updates, read MAINTENANCE.md before choosing a file to edit.

Route a request

1. Identify the task: draft, revise, audit, explain, or translate. Compilation and build diagnosis belong to the separate latex-compile skill. Also identify whether this is a brief chat answer/local lookup or a substantial persistent artifact. The full source-grounded workflow applies conditionally to substantial explanations; reports and textbooks follow their type contracts.
2. Select exactly one primary type under references/types/: report, explanation, or textbook.
3. If the primary type has a bounded variant or component, load it from references/type-addons/: report-experiment or textbook-exercises. An add-on does not become a second primary type.
4. Add zero or more cross-type lenses under references/lenses/: derivation-analysis for derivation-heavy exposition and mechanism-analysis for input/output/state/control-flow depth. Activate a lens when the source or requested deliverable contains the corresponding analysis; do not require the user to name the lens explicitly. The mechanism lens contains an optional deep-dive question bank; use only the relevant groups.
5. Add source objects under references/objects/ when the task relies on identifiable evidence sources: paper, repository, or both. Add a domain module only when the subject has domain-specific evidence or terms.
6. For a source artifact, select exactly one format under references/formats/: Markdown, LaTeX, or Typst. Chat-only prose selects no format.
7. Resolve exactly one format according to Format resolution below. Load a format integration only for a real type-format or package interaction that cannot be expressed cleanly in the type and format modules. The initial exception integrations are scholia-typst and textbook-latex under references/format-integrations/.
8. Load references/common/writing.md for every reader-facing output. Add common/evidence-and-citations.md when claims depend on research, measurements, code, or other sources; that module owns the shared ledger.
9. Activate reviewers and checks according to the Reviewer and check activation matrix below. A reviewer role is not a checklist: use reviewers/reader.md and/or reviewers/source-reviewer.md when their isolation and output contracts are required.

Do not load every module by default. If the request is ambiguous, preserve the uncertainty and ask for the missing type, object, or format rather than silently composing a large bundle.

Module map

Composition examples

• Ordinary paper explanation: explanation + paper object. Add lenses and choose the format only when the source or deliverable requires them.
• Repository explanation: explanation + repository object. Paper facts are out of scope unless a paper object is also active.
• TENG Typst explanation: explanation + paper + derivation-analysis + mechanism-analysis + Typst; add the domain module only if its subject policy is needed.
• GPU-kernel paper/repository explanation: explanation + paper + repository
  • gpu-kernel + mechanism-analysis + chosen format.
• Ordinary Typst report: report + Typst. Do not load scholia-typst.
• Experiment report: report + report-experiment; default to LaTeX when no existing or explicit format is supplied, then add evidence and rendered checks when applicable.
• LaTeX textbook: textbook + LaTeX + textbook-latex; add exercises only when exercises are part of the deliverable.

Reviewer and check activation

Use the following defaults unless the user explicitly narrows the task:

Reviewer coordination

Use these Main-agent rules when more than one isolated reviewer is active or a delegated persistent review is requested. Reader comprehension and source grounding are separate judgments; neither reviewer silently replaces the other's role.

Arbitration

• Evidence boundaries from the active object policies cap every completeness request. Reader preference cannot turn an undocumented detail into a fact.
• If a comprehension issue blocks the central mechanism, it takes priority over stylistic brevity. Add only the smallest source-supported bridge.
• Add detail only when it serves the contribution, is source-disclosed, or is explicitly requested. Refuse deletion when it would break an input/output, condition, state-update, derivation, or evidence chain.
• Preserve not specified boundaries when the source is silent. A reviewer may recommend narrowing or labeling a claim, not filling it from general knowledge.

Completion and release

• For a persistent artifact or delegated review, retain the structured review result until the task reaches its final handoff. A chat-only answer does not require a Reviewer YAML file to be persisted.
• If delegation is unavailable, run the same roles sequentially with the same source and draft isolation boundaries.
• Finish only after the applicable Reader, Source Reviewer, active lens checks, figure/artifact coverage, document source-claim and prose sections, and the rendered section have passed or their remaining limitations are explicitly reported.

Format resolution

When the user edits an existing source file, preserve its format even if the user does not repeat it. Otherwise use explicit user format, then a bounded type/add-on default, and finally Markdown as the writer default. The default for report + report-experiment is LaTeX because the experiment contract and its established report assets are LaTeX-oriented; an explicit format always overrides it.

For revisions, read the current document before editing. Inspect the working tree diff and relevant Git history when they reveal user changes or durable revision preferences. Preserve unrelated edits and do not restore deleted material merely because it existed in an older version.

Review and evidence boundaries

• objects/ defines what a source can establish; it does not define the prose shape of the deliverable.
• lenses/ adds questions or narrative behavior that can apply to more than one primary type.
• reviewers/ defines isolated agent roles and structured verdicts. A source reviewer reads the active object policies; it is not paper-only.
• Never turn a diagram arrow, repository convention, or plausible implementation into a source fact without evidence. Mark an omitted detail not specified.
• Keep paper claims, repository behavior, and clearly labeled inference separate, including when both objects are active.

Boundaries

• Do not invent data, citations, theorem steps, experimental conditions, implementation details, or numerical results.
• Follow a user-provided journal, course, laboratory, or house template before generic conventions.
• Treat autoreport as a separate orchestration skill. When it delegates report-body writing, route only the body through this skill; do not absorb its data analysis, plotting, or orchestration responsibilities.
• Treat latex-compile as a separate build and diagnosis skill. Do not embed its compiler workflow here.
• The canonical rules live under writer; the removed legacy entry points are not part of routing. Do not recreate them or copy their rules into a new wrapper.