---
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 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 backlog issue 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
  Gitea backlog as candidates for a follow-up tidy iteration.