Brummel
26e9630496
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing). Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign. Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
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 project's doc-build command (its CLAUDE.md project facts) 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.