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.
90 lines
3.7 KiB
Markdown
90 lines
3.7 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
|
|
|
|
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.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.
|