Skills/docwriter/SKILL.md

name, description

name	description
docwriter	Use when the API surface of one or more components has stabilized across recent cycles and API-doc lag is suspected (the project's documentation tool shows accumulated warnings, or a newcomer would not be able to navigate the generated docs without the design ledger). NOT a per-cycle step; orchestrator-dispatched only, after audit closes clean and after any pending fieldtest has run.

docwriter — post-stability documentation sweep

Violating the letter of these rules is violating the spirit.

Overview

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

When to Use / Skipping

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

• The command configured under commands.doc_build in the project profile shows accumulated warnings across multiple components after a stability window of several cycles.
• A backlog issue like "doc warning sweep" has matured — the surface it targets has not moved for a while.
• Onboarding-readability check: navigating the generated docs for a component 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-CYCLE.
NO API CHANGES — DOCS ONLY.
IF THE CODE STILL FEELS LIKE IT MIGHT GET REWRITTEN, DON'T DOCUMENT IT YET.

Dispatch

The orchestrator dispatches docwriter with scope, warning_target, and optional priority_items. The agent carries the substantive rules — what counts as top-level, module-level, and item-level documentation in this project's doc system; 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
scope	Component / package / crate / module name(s) to document, or all
warning_target	Specific doc-tool 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 (top-level / module-level / item-level)
warnings_cleared	count, plus the doc-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: agents/docwriter.md — carries the documentation rules, hard limits, verification triple, Common Rationalisations, and Red Flags.
• Pre-condition (upstream): ../audit/SKILL.md must have closed clean (or with ratified drift only). Docwriter does not run on a cycle with open drift.
• Pre-condition (upstream, conditional): ../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: the orchestrator. Findings flow into the project's issue backlog as candidates for a follow-up tidy iteration.