Brummel
7f46e9c027
Third skill via the boss pattern. docwriter was the most language-coupled of the seven (Rust rustdoc, cargo doc, /// + //!, intra-doc links). Generalised the discipline while keeping Rust as the canonical concrete example, with a note that other languages substitute syntax (TSDoc, Python docstrings, Javadoc). Profile gains one slot: - `commands.doc_build` — doc-build command that prints warnings on stderr (e.g. "cargo doc --no-deps 2>&1"); used by the docwriter agent's verification triple and warning enumeration. Optional — projects without API docs omit it. Vocabulary substitutions: - AILang → "this project" - "crates" → "components / packages / crates / modules" (the project's idiom) - "milestone" → "cycle" - "Boss" → "orchestrator" - "ailang-docwriter" → "docwriter" AILang-specific bits replaced: - `cargo doc --no-deps 2>&1` → `commands.doc_build` slot - `cargo build --workspace` / `cargo test --workspace` → `commands.build` / `commands.test` slots - `crate / module / item` levels → "top-level / module-level / item-level" (the universal taxonomy; concrete syntax via language note) - `src/lib.rs` / `src/main.rs` hardcoded paths → "entry-point file" (Rust example kept inline) - `docs/` / `design/` hardcoded dirs → `paths.design_ledger`, `paths.design_contracts`, `paths.design_models`, `paths.spec_dir` slots Universal substance preserved verbatim: - Iron Law (4 lines) - Documentation rules (5 bullets) — substantive content; only the concrete-syntax examples got the Rust-as-example note - Hard limits (4 bullets) - Verification triple (build / test / doc_build) - Status protocol (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED) - All 7 Common Rationalisations rows (with vocabulary edits) - All 7 Red Flags bullets
97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
---
|
|
name: docwriter
|
|
description: 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.
|