Files

T

Brummel 176821c2e7 iter design-md-rolesplit.1 (DONE 9/9): DESIGN.md -> design/ ledger role-split

The 3020-line docs/DESIGN.md is replaced by the design/ ledger:
design/INDEX.md (sole addressable spine, typed Contracts+Models tables,
polymorphic links — prose file OR authoritative source //!), 14
design/contracts/*.md test-linked invariants + 3 source-link-only
contracts (mangling/env-construction/qualified-xref, no prose file —
code is SoT), 5 design/models/*.md whitepapers, and
docs/journals/2026-05-19-design-decision-records.md (the
relitigation-guard archive — every why/rejected/does-not-do/rollback/
empirical ### moved out at ###-granularity). Clean cut: git rm
docs/DESIGN.md, no stub.

RED-first crates/ailang-core/tests/design_index_pin.rs — the 4-clause
anti-regrowth spine (DESIGN.md-gone / every-INDEX-link-resolves /
every-contract-names-a-resolvable-ratifier /
contracts-carry-no-decision-record-prose) — demonstrably RED before,
GREEN after. Build-atomic by task ordering: design_schema_drift.rs's
include_str! (the only compile-time consumer) retargeted to
design/contracts/data-model.md BEFORE the deletion; its
## Data model/## Pipeline slicer dropped (a simplification the split
enables). 2 NoInstance diagnostics + 2 lockstep E2Es retargeted to
design/contracts/{float-semantics,typeclasses}.md. ~12 agent reading
lists + 5 SKILL bodies + CLAUDE.md + skills/README.md + ~25
code/C/.ail/spec comment xrefs retargeted; OQ7 dangling 'Iter 13b'
cite deleted (no forward target — a pointer would be fiction).
honesty-rule.md rewritten so the rule names the new home
(rationale->journals), resolving the recon-found internal
contradiction; the two docs_honesty_pin.rs:70,72 pinned phrases kept
verbatim+contiguous.

Boss-verified independently: cargo test --workspace 646 passed /
0 failed; design_index_pin 4/4; acceptance grep CLEAN of live
DESIGN.md refs (residuals = only the spec-mandated clause-4
deletion-enforcer). 2 DONE_WITH_CONCERNS routed to the mandatory
milestone-close audit: (a) str-abi.md:23 '(iter str-concat,
2026-05-13)' provenance stamp trips advisory architect_sweeps Sweep-1
— Boss-confirmed byte-identical to DESIGN.md@deeffb1:2062-2065, a
faithfully-migrated PRE-EXISTING anchor (regexes verbatim, only path
retargeted), NOT split-introduced — RATIFY-or-tidy at audit; (b) a
now stale-direction intra-prose 'see Str ABI below' cross-ref in
float-semantics.md — audit-adjudication candidate. Plan defect noted:
Task 9 Step 4's verbatim acceptance grep used a ^./ anchor not
matching the system's grep -rIn output; substance re-verified CLEAN.

Spec grounding-check PASS x2. Journals INDEX + decision-records
pointer appended (Boss-only).

2026-05-19 13:04:22 +02:00

3.8 KiB

Raw Blame History

name, description

name	description
docwriter	Use when the API surface of one or more crates has stabilized across recent milestones and rustdoc lag is suspected (cargo doc --no-deps shows accumulated warnings, or a newcomer would not be able to navigate the crate from `cargo doc --open` without the design/ ledger). NOT a per-milestone step; Boss-dispatched only, after audit closes clean and after any pending fieldtest has run.

docwriter — post-stability rustdoc sweep

Violating the letter of these rules is violating the spirit.

Overview

Rustdoc rots silently. Every iteration changes APIs and module boundaries; doc comments lag. Running this sweep per-milestone is waste — documenting an item that gets renamed two iterations later just burns context. The right moment is post-stability: after a stretch of milestones in which the surface in question has held still. This skill is the third bucket in the cadence taxonomy (per-milestone-mandatory audit; Boss-judgment post-audit fieldtest; Boss-judgment post-fieldtest docwriter), and it fires on Boss judgment, never on a milestone clock.

When to Use / Skipping

Boss-dispatched only. Audit closing does not trigger docwriter. Trigger conditions are any of:

cargo doc --no-deps 2>&1 shows accumulated warnings across multiple crates after a stability window of several milestones.
A roadmap entry like "Rustdoc warning sweep" has matured — the surface it targets has not moved for a while.
Onboarding-readability check: navigating cargo doc --open for a crate is not self-supporting without the design/ ledger.

Skipping is the default. The skill only runs when the orchestrator positively decides the surface is stable enough to document. If the code still feels like it might get rewritten, do not dispatch — wait.

The Iron Law

DOCWRITER IS POST-STABILITY, NOT PER-MILESTONE.
NO API CHANGES — DOCS ONLY.
IF THE CODE STILL FEELS LIKE IT MIGHT GET REWRITTEN, DON'T DOCUMENT IT YET.

Dispatch

The orchestrator dispatches ailang-docwriter with crate_scope, warning_target, and optional priority_items. The agent carries the substantive rules — crate-root vs. module-root vs. item docs, intra-doc link conventions, the verification triple. This SKILL.md only governs trigger and dispatch; the agent file governs the work.

Handoff Contract

docwriter consumes (from orchestrator):

Field	Content
`crate_scope`	Crate name(s) to document, or `all`
`warning_target`	Specific rustdoc warnings to clear, or `all`
`priority_items`	Optional: items the orchestrator wants documented first

docwriter produces:

Field	Content
`status`	`DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`
`files_touched`	paths + which level (crate / module / item docs)
`warnings_cleared`	count, plus the rustdoc check status
`findings`	items whose names or behaviour seemed confusing while documenting them (one line each, no prescriptions)

The orchestrator decides whether findings become a follow-up iteration; docwriter does not self-resolve.

Cross-references

Agent dispatched: skills/docwriter/agents/ailang-docwriter.md — carries the documentation rules, hard limits, verification triple, Common Rationalisations, and Red Flags.
Pre-condition (upstream): skills/audit/SKILL.md must have closed clean (or with ratify-d drift only). Docwriter does not run on a milestone with open drift.
Pre-condition (upstream, conditional): skills/fieldtest/SKILL.md — if a fieldtest is pending for the surface in scope, run it first. Fieldtest can surface bugs or architecture problems that would invalidate the doc work.
Hand-off target: orchestrator (me). Findings flow into the roadmap as candidates for a follow-up tidy iteration.

3.8 KiB Raw Blame History