From e3519692953a69916f5421486afafa4b2229c312 Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 11 May 2026 13:54:34 +0200 Subject: [PATCH] =?UTF-8?q?iter=20cadence.1:=20skills/docwriter=20?= =?UTF-8?q?=E2=80=94=20new=20Boss-dispatched=20skill=20(split=20from=20aud?= =?UTF-8?q?it)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/agents/docwriter | 1 + .claude/skills/docwriter | 1 + skills/docwriter/SKILL.md | 89 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+) create mode 120000 .claude/agents/docwriter create mode 120000 .claude/skills/docwriter create mode 100644 skills/docwriter/SKILL.md diff --git a/.claude/agents/docwriter b/.claude/agents/docwriter new file mode 120000 index 0000000..523f61d --- /dev/null +++ b/.claude/agents/docwriter @@ -0,0 +1 @@ +../../skills/docwriter/agents \ No newline at end of file diff --git a/.claude/skills/docwriter b/.claude/skills/docwriter new file mode 120000 index 0000000..9f392c0 --- /dev/null +++ b/.claude/skills/docwriter @@ -0,0 +1 @@ +../../skills/docwriter \ No newline at end of file diff --git a/skills/docwriter/SKILL.md b/skills/docwriter/SKILL.md new file mode 100644 index 0000000..1ac9f51 --- /dev/null +++ b/skills/docwriter/SKILL.md @@ -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.