Brummel
fc0e1d0d46
Per-skill prose tightening from the same audit swarm; each finding passed an adversarial second reviewer. No behavioural change. - audit: drop garbled "Conventions require deferred audits to compound" sentence (says the opposite of intent; the preceding line already closes the loophole). - brainstorm: drop forward-pointing meta-comment about the Rationalisations table. - debug: drop third restatement that debugger.md is the single source for the carrier/handoff fields. - docwriter: drop motivational opener; Overview starts at the waste argument. - fieldtest: fold the 2-4-examples rationale into the dispatch sentence instead of restating the count a fourth time. - implement: drop "known platform constraint at the time" aside. - planner: cut the verbose anti-drift paragraph (which restated the very table it claimed not to) down to a cross-reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3.7 KiB
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
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_buildin 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) the carrier fields
scope, warning_target, and priority_items, defined
authoritatively under Carrier contract in agents/docwriter.md.
docwriter produces, for the orchestrator, the fields status,
files_touched, warnings_cleared, and findings, defined
authoritatively under Output format (with the status enum in
the Status protocol) in agents/docwriter.md.
Both contracts are single-sourced in the agent file; they are deliberately not restated here, so the two files cannot drift.
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.mdmust 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.