Brummel
0b969838c0
Apply the debug-skill pattern (commits 6410732..de42974) to the remaining skills: the agent file is the single source for each interface field's semantics; the SKILL.md copy is reduced to field names plus a pointer, marking the agent's contract table authoritative. Because SKILL.md loads into orchestrator context and agents/*.md into the subagent's fresh system prompt with no transclusion, duplicated field tables drift apart over time. - brainstorm: carrier (spec_path/iteration_scope) -> grounding-check; the absolute-path requirement now lives only in the agent. - planner: carrier (spec_path/iteration_scope/focus_hint) -> plan-recon, including the mandatory/optional markers and the BLOCKED-on-missing rule SKILL.md had omitted. - fieldtest: carrier + produced fields -> fieldtester; the skill-level `status` roll-up (clean/friction_found/bugs_found/infra_blocked), which is not part of the agent's run-status protocol, stays defined in SKILL.md only. - docwriter: carrier + produced fields -> docwriter agent. - implement: carrier (iter_id scratch-dir/stats/not-a-branch semantics) -> implement-orchestrator; per-task sub-status vocabulary moved into the orchestrator-agent (it runs the loop in a fresh context and could not read SKILL.md at runtime, yet referenced "the sub-status table" by name); task_text_path single-sourced in implementer with spec-reviewer cross-referencing. audit was already the reference implementation (pointers, no restated contracts) and is unchanged. closes #2 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
92 lines
3.8 KiB
Markdown
92 lines
3.8 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) 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.
|