Technical-writing curriculum #

This directory teaches writing judgment before asking a model to maintain a real repository. It is separate from the source-grounded documentation corpus in config/sources.toml.

The corpus answers, “Which maintained pages can we align to exact code evidence?” The curriculum answers, “Which decisions must a technical writer learn, in what order, and how do we know the decisions survived later training?” Mixing those questions produced the first failed experiment: the model saw complete pages before it had practiced audience, scope, document type, or revision.

Stages #

Stage	Goal	Primary output
01-sentence-mechanics	Make local prose exact and economical without changing meaning.	A sentence, list, or paragraph edit.
02-reader-and-purpose	Choose the audience, user goal, scope, and document type before drafting.	A writing brief or classified document intent.
03-diagnosis-and-revision	Find a concrete defect, name it accurately, and make the smallest sufficient repair.	A diagnosis plus revised passage.
04-information-architecture	Arrange material around user movement rather than product inventory.	An outline, content split, or reordered document.
05-source-grounded-composition	Turn bounded implementation evidence into one useful documentation unit.	A grounded section or short page.
06-editorial-review	Review a complete draft across factual, rhetorical, and usability dimensions.	A review decision and revised draft.
07-repository-maintenance	Inspect a repository, update the right documentation, verify the effect, and stop.	A successful Pi filesystem-effect trajectory.

The order describes prerequisites, not a claim that every example has a universal scalar difficulty. A short audience decision can require more judgment than a long rewrite. Each record therefore carries explicit difficulty axes instead of using token count as a substitute for difficulty.

Contents of a stage #

Every stage owns the same small set of artifacts:

• README.md: competency boundary, lessons, failure modes, and completion gate;
• stage.toml: machine-readable identity, prerequisites, task families, and file paths;
• GENERATION.md: how to produce candidates without quietly changing the task;
• rubric.toml: weighted criteria and non-compensable gates;
• examples/train.jsonl: checked-in seed demonstrations or task specifications;
• examples/eval.jsonl: held-out seed cases used to prove the stage remains measurable.

Seed records are examples of the contract, not a dataset large enough to train. They anchor generation, review, and regression tests. Generated candidates remain under artifacts/ until their source, license, target, and rubric receipts pass.

Shared contracts #

• shared/RECORDS.md defines seed and generated record shapes.
• shared/GENERATION.md defines teacher generation and acceptance.
• shared/TRAINING.md defines expanding replay and stage promotion.
• shared/EVALUATION.md defines cumulative evaluation.
• shared/PROVENANCE.md defines source and license custody.
• shared/QUALITY_MODEL.md defines the cross-stage quality dimensions.
• sources.toml registers every teaching reference and its permitted use.
• generation.toml defines a bounded first candidate-generation pilot.
• schemas/generation-assignment.schema.json defines the provider-free assignment envelope emitted before prompt binding.
• prompts/teacher-v1.md and prompts/reviewer-v1.md define separate generation and review roles.
• The remaining schemas separate teacher output, frozen bindings, proposed candidates, reviewer output, and accept/reject decisions. Proposed candidates deliberately omit final example IDs and dataset splits.
• schedule.toml supplies the initial expanding replay mixture.

Validate #

Run:

uv run docwriter validate-curriculum
uv run docwriter compile-curriculum-seeds --output-dir artifacts/curriculum-seeds
uv run docwriter plan-curriculum-generation \
  --output-dir artifacts/curriculum-generation-plan

Validation checks documents, source statuses, stage order, prerequisites, rubric weights, example provenance, message shape, split identity, generation coverage, schedule weights, and cumulative evaluation coverage. Seed compilation freezes supervised train and evaluation records plus repository train and evaluation task specifications into four deterministic files with hashes. Generation planning allocates every requested candidate across task family, difficulty, target skill, source, synthetic universe, and train-only demonstrations. All three commands are deterministic and make no provider call.

Training boundary #

Stages 1–6 can compile to ordinary provider-neutral supervised records. Stage 7 compiles to target-masked Pi tasks first. Only successful, effect-checked Pi sessions become per-assistant-decision trajectory data.

The curriculum never authorizes paid generation or training. A generated dataset still requires a frozen build receipt; a provider operation still requires the selected profile, explicit execution flag, printed cost bound, and the operator's fresh authorization.