iter cadence.1: skills/docwriter — new Boss-dispatched skill (split from audit)

2026-05-11 13:54:34 +02:00
parent 34238388a1
commit e351969295
3 changed files with 91 additions and 0 deletions
@@ -0,0 +1 @@
+../../skills/docwriter/agents
@@ -0,0 +1 @@
+../../skills/docwriter
@@ -0,0 +1,89 @@
+---
+name: docwriter
+description: 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 DESIGN.md). 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 DESIGN.md.
+
+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.