Clean Docs

Clean-Docs Skill (CAFleet-orchestrated)

One skill, three workflows — residue, affirmative, simplification — run as the same CAFleet team shape over the same per-run process. This page is the dispatcher and the single home of the shared orchestration spine; each workflow body (<workflow>/<workflow>.md) carries only its own trigger scenario, scan mechanics, artifact spec, and guarantees, citing the spine here rather than restating it.

Required reading

Identify your coding agent first — a member's spawn prompt names it on the CODING AGENT: line; the Director (main session) uses its own identity — then Read your overlay and resolve it before your first action.

Load-bearing — Read in order before acting:

The workflow body you route into carries its own Required-reading block for the workflow's reference pages (rubric, pattern catalog, shared review format).

Before acting, resolve every {token} you will use to its overlay value (or the documented default); a literal {token} in any command, message, or user-facing string is a defect.

Dispatch

Route the user's request into exactly one workflow body by phrasing, then run that body's orchestration in full over the spine below. One workflow per run — never a combined pass. When a request names families from more than one workflow, the Director asks the user which single workflow to run via {decision_surface}.

Class-to-workflow split

Every candidate a scanner may act on belongs to exactly one workflow. The class identifiers are canonical in each workflow's rubric; ownership is:

Boundary tie-break. A candidate whose fix would change prohibition structure, voice, or code behavior belongs to affirmative, even when it is also verbose — the affirmative rewrite subsumes the tightening. A candidate whose fix only removes words or duplication with unchanged voice belongs to simplification. Past-tense narration always belongs to residue. A scanner never proposes another workflow's classes: it records cross-workflow candidates in its artifact's Observations section (see Observations escalation channel below) for the Director to report, so the user can schedule the other workflow.

Three invariants (every workflow, every run)

1. No contract or behavior lost. Every CLI flag, error string, schema, command example, IMPORTANT line, and cross-reference survives — in fewer words, never in weaker form. Sole exception: an approved affirmative-workflow P4 row, which changes behavior deliberately (fallback → fail-fast); each P4 row names its covering tests or is explicitly marked "uncovered", and lands only with the reviewer's individual acceptance — an "uncovered" row only with that acceptance made explicit. Residue and simplification runs are strictly zero-behavior-change.
2. No live test coverage lost. Test logic, assertions, fixtures, and parametrizations are untouchable; only comments, docstrings, and sentinel framing are in scope. A mixed sentinel test keeps its live assertion.
3. No new narration (R1). Every edit reads as a clean present-tense statement of current behavior — no "previously / now / formerly", no "this replaces X", no "renamed from Y".

Scope and exempt set

In scope: the whole tracked tree minus the exempt set. Exempt (never modified): design-docs/, researches/, and lock files. The design/research folders are the historical record.

Per surface, the scope of what may change:

Team shape

User → /clean-docs (one workflow)
 └─ Director (main session — resolves BASE, bootstraps fleet + monitor
              member atomically, partitions slices, merges partials,
              holds the apply behind review, verifies, commits when asked,
              deletes the monitor member first at teardown)
     ├─ scanner-1  (owns a disjoint file slice: scan → propose → apply after gate)
     ├─ scanner-N  (…)
     └─ reviewer   (the workflow's guard, --model {reviewer_model})

Disjoint file-ownership is the concurrency contract. No two scanners edit the same file, so parallel apply is safe without worktrees. One scanner owns every edit to a given file, regardless of class — a file touched by several classes is assigned whole to one scanner. A useful default partition: docs+root files / skills+.claude / source+admin / tests — merge or split slices to balance the scanner count against the tree size.

Coordination

The skill adopts the cafleet verb + pointer schema (skills/cafleet-design-doc/reference/coordination.md) with two skill-local extensions, since a run produces a run artifact, not a design document:

• Role taxonomy gains a scanner role for COMMENT(scanner) markers.
• Pointer: a per-workflow whole-run pointer denotes the run artifact as a whole — inventory for residue, findings for affirmative and simplification. Scanners report complete (<run pointer>); the reviewer's gate is approved (inventory) / approved (findings) (or blocked (<run pointer>)); per-row routing uses <file>:<line> pointers.

Per-run process

1. Resolve ${BASE} — task-scoped per the cafleet skill's reference/base-dir.md, convention researches/clean-docs-<workflow>-<UTC-compact>/ (gitignored, one folder per run).
2. Bootstrap — cafleet doctor (gating), then cafleet fleet create --monitor-file <abs path to ${BASE}/.prompts/monitor-<UTC-compact>.md> --monitor-model {monitor_model} (one atomic command: fleet + Director + monitor member; members spawned {permission_flags}); gate the first ordinary spawn on the monitor's monitor live message (the CLI monitor-first guard backstops).
3. Spawn workers — scanners (one per disjoint slice) and the reviewer (--model {reviewer_model}), each from a rendered prompt at ${BASE}/.prompts/<role>-<UTC-compact>.md.
4. Scan (fan-out) — each scanner runs the workflow's scan mechanics (parameter table below) over its slice and writes its partial artifact under ${BASE}, with a separate Observations section.
5. Merge + review (gate) — the Director merges partials into the run's canonical artifact and routes it to the reviewer with ready (<run pointer>). No repository edit happens before the reviewer's approved (<run pointer>).
6. Apply — the Director relays approval; each scanner applies its own slice's approved rows exactly as written. A scanner whose harness denies a write (commonly .claude/) stages the full target file under ${BASE}/.apply/ and routes to the Director, who diff-reviews the staged file and applies it.
7. Verify — mise //cafleet:test, mise //cafleet:lint, mise //cafleet:typecheck green, plus the workflow verification (parameter table below).
8. Report + teardown — the Director reports the applied set and the escalated observations, commits only when the user asks, and tears down (delete the monitor member first — the pane kill takes the loop down — → delete the remaining members → verify via member list → fleet delete).

Workflow parameter table

The spine is parameterized by exactly three per-workflow values:

Observations escalation channel

While scanning, a scanner records — and never fixes — content drift (two surfaces disagreeing, a broken cross-reference, a doc contradicting the code) and cross-workflow candidates (Class-to-workflow split above) in its artifact's Observations section. The Director escalates them to the user in the run report. The applied cleanup — the git diff plus green verification — is the real deliverable; observations are escalated, never self-applied.

${BASE} convention

Task-scoped per the cafleet skill's reference/base-dir.md: researches/clean-docs-<workflow>-<UTC-compact>/ (gitignored, one folder per run). Agent-only scratch is dot-prefixed: .prompts/ (spawn-prompt renders), .apply/ (staged harness-denied writes).

Spawn-prompt skeleton

One skeleton for all three workflows, with the workflow named in the role line and the role-definition path pointing into <workflow>/roles/. The Director renders each [INSERT …] marker to a literal before writing; leaves the four {fleet_id} / {member_id} / {director_member_id} / {coding_agent} identity placeholders for the CLI's str.format at spawn; doubles every OTHER literal brace as {{ / }}:

You are the <role> in a clean-docs <workflow> team (CAFleet-native).

ROLE DEFINITION: Open [INSERT abs path to <workflow>/roles/<role>.md] with the Read tool BEFORE any other action.

Load these skills at startup:
- the clean-docs skill — for the shared spine and your workflow's mechanics
- the cafleet skill — for the broker primitives and bash-via-Director routing

FLEET ID: {fleet_id}
DIRECTOR MEMBER ID: {director_member_id}
YOUR MEMBER ID: {member_id}
BASE: [INSERT abs BASE path the Director resolved]
CODING AGENT: {coding_agent}

<role-specific assignment: the scanner's slice path list + partial-artifact path,
 or the reviewer's merged-artifact path>

IMPORTANT: Read and follow .claude/rules/bash-tool.md (CAFleet-member Bash protocol) and ~/.claude/rules/bash-command.md (general Bash hygiene) for all Bash commands.
IMPORTANT: If blocked, send a message to the Director immediately instead of assuming.
IMPORTANT: Do NOT edit any repository file until the Director relays the reviewer's approved (<run pointer>). The scan phase is read + propose only.
IMPORTANT: Do NOT commit code or run git write operations — the Director handles all git.

On spawn, as your first Bash call, send the ready signal: cafleet message send --from-member-id {member_id} --to-member-id {director_member_id} "ready"

When you see cafleet message poll output with a message from the Director, act on those instructions.

<start cue: scanner — begin the scan of your slice; reviewer — wait for ready (<run pointer>)>

Backend-neutrality

SKILL.md, the workflow bodies, and every <workflow>/roles/*.md are backend-neutral: they use {bg_run} / {reviewer_model} / {skill_loader} / {decision_surface} / {permission_flags} tokens resolved from the member's backend section of ../../../skills/cafleet/reference/coding-agent-overlays.md, and every member's spawn-prompt identity block carries a CODING AGENT: {coding_agent} line so the member resolves its overlay. Role files are referenced by absolute path in spawn prompts (never inlined); spawns use --file.

Skill file layout

.claude/skills/clean-docs/
  SKILL.md                        # this file — dispatch + shared spine, backend-neutral
  reference/
    review-format.md              # shared by affirmative + simplification: row format, guardrails, verdict flow
  residue/
    residue.md                    # workflow body — sweep mechanics + completeness guarantee
    roles/scanner.md              # sweep → hand-inspect → classify → apply own slice
    roles/reviewer.md             # over-deletion / lost-coverage / R1 guard
    reference/rubric.md           # (a)/(b)/(c) + known-benign — canonical
    reference/patterns.md         # pattern catalog + exempt-set exclusion — canonical
  affirmative/
    affirmative.md                # workflow body — P1/P2/P4 judgment review
    roles/scanner.md              # full read → propose → apply own slice after the gate
    roles/reviewer.md             # lost-meaning / lost-contract / behavior-change guard
    reference/rubric.md           # P1, P2, P4 classes — canonical
  simplification/
    simplification.md             # workflow body — P3/P5 judgment review
    roles/scanner.md
    roles/reviewer.md
    reference/rubric.md           # P3, P5 classes — canonical