Files

T

Brummel 0b969838c0 refactor: single-source carrier/handoff contracts across skills

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>

2026-05-30 11:10:10 +02:00

3.8 KiB

Raw Blame History

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

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.

3.8 KiB Raw Blame History