Clean Docs

---
name: clean-docs
description: >
  Clean up the repository's docs, comments, rules, and tests as a CAFleet team
  of disjoint-slice scanner members gated by a reviewer — exactly one workflow
  per run. Use the residue workflow when the user asks to clean up historical
  narration or historical residue, remove deprecation notes / "this replaces X"
  / "renamed from Y" / "previously … now …" prose, drop design-number
  provenance citations, or remove historical sentinel framing while preserving current absence tests. Use the affirmative
  workflow when the user asks to run an affirmative-writing sweep, fix
  prohibition-only rule sections, pair prohibitions with affirmatives, remove
  meaningless fallbacks, or make code fail fast. Use the simplification
  workflow when the user asks to simplify the docs or comments, tighten verbose
  prose, de-duplicate documentation, or remove redundant comments. Nothing is
  applied before the reviewer approves the merged run artifact. Members load
  this skill by its name clean-docs via their backend's skill-loader.
---

# 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.

Resolve runtime tools from the executing agent's backend. For spawns, read the selected member backend's Model catalog and Role defaults under the CAFleet Director's model-selection policy; validate its effort and launch capabilities there. Monitor bootstrap and recovery inherit the Director's backend. Interpret captured panes using the observed member's backend cues.

## Required reading

Identify the executing backend (members use `CODING AGENT`), resolve its [runtime bindings](../../../skills/cafleet/reference/coding-agents.md), and load `cafleet` for BASE, member startup or Director orchestration. Read [coordination](../../../skills/cafleet-design-doc/reference/coordination.md) for verbs, pointers and marker pairing, then this shared spine once. A workflow's Required reading adds only its phase-specific prerequisites. Resolve model tokens from the selected spawn backend's Role defaults, runtime tokens from the executing backend, and capture cues from the observed backend; use documented defaults only in their allowed cases.

## 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}`.

| When the user wants to… | Run |
|:--|:--|
| Clean up historical narration / historical residue; remove deprecation notes, "this replaces X" / "renamed from Y" / "previously … now …" prose; drop design-number provenance citations; remove historical sentinel framing while preserving current absence tests | the **residue** workflow ([residue/residue.md](residue/residue.md)) |
| Run an affirmative-writing sweep; fix prohibition-only rule sections; pair prohibitions with affirmatives; remove meaningless fallbacks; make code fail fast | the **affirmative** workflow ([affirmative/affirmative.md](affirmative/affirmative.md)) |
| Simplify the docs / comments; tighten verbose prose; de-duplicate documentation; remove redundant comments | the **simplification** workflow ([simplification/simplification.md](simplification/simplification.md)) |

### 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 classification section; ownership is:

| Workflow | Owns | Fix character |
|---|---|---|
| **residue** | (a) sentinel framing, (b) narration/citation/trajectory, (c) keep + known-benign | Remove historical framing; preserve current absence tests and reword narration to present tense. Strictly zero behavior change. |
| **affirmative** | **P1** prohibition-pile, **P2** unpaired prohibition (including negatively-phrased instructions rewritable in affirmative voice), **P4** meaningless fallback / swallowed error | Fixes that change prohibition structure, voice, or code behavior. P4 rows are BEHAVIOR-AFFECTING — the only permitted behavior change in any workflow (invariant 1). |
| **simplification** | **P3** redundant prose, **P5** verbose phrasing (verbosity only — the 30%+ word-reduction baseline; voice rewrites belong to P2) | Fixes that only delete redundancy or reduce words, with voice and behavior unchanged. Strictly zero behavior change. |

**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. Preserve current-behavior absence tests, including native parser rejection; a framing edit retains all test logic and assertions.
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:

| Surface | In scope | Untouchable |
|---|---|---|
| `docs/`, `README.md`, `SPEC.md`, skills, rules | prose structure and wording | contract detail (exact flags, error strings, schemas, layouts), command examples, IMPORTANT / lossless-rule lines, backend-neutral base/overlay separation |
| source code | comments, docstrings, affirmative-workflow P4 fallback sites | flags, options, columns, code paths, log/user-facing/error strings |
| tests | comments, docstrings, sentinel framing | all logic, assertions, fixtures, names |

## 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})
```

| Role | Responsibility |
|---|---|
| **Director** | Resolve task-scoped `${BASE}`; bootstrap the fleet with the monitor member included (`cafleet fleet create --monitor-file <abs path> --monitor-model {monitor_model}` plus supported monitor effort) and gate the first ordinary spawn on its `monitor live` message (the CLI monitor-first guard backstops); partition the in-scope tree into **disjoint file-ownership** slices (one file → one scanner, whole surfaces per scanner); merge partial artifacts into the run's canonical artifact; route it to the reviewer and **hold the apply until the reviewer's approval**; relay approval to scanners; apply a denied write through the full-file staging protocol; run verification; escalate observations to the user; delete the monitor member first (first-out) at teardown. |
| **scanner** (×N) | For its slice: run the workflow's scan mechanics, propose actions per the workflow's rubric, record observations separately, write its partial artifact under `${BASE}`. After approval is relayed: apply its own slice's approved rows exactly as written, re-verify its diff, route harness-denied writes to the Director. |
| **reviewer** | Validate the merged artifact **before** any edit, per the workflow's guarantees and guardrails. After apply: run the workflow verification (parameter table below). |

**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} [--monitor-effort {monitor_effort}]` (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, using the other-member defaults) and the reviewer
   (`--model {reviewer_model}` with supported reviewer effort), 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. Use the full-file staging protocol for a denied write.
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`).

### Full-file staging

Every scanner reads this protocol before application. For a harness-denied target write, stage the **complete replacement file** under `${BASE}/.apply/`, retaining its relative target path. Compare it with the current repository file: the diff must contain exactly the Director-relayed approved rows, including reviewer REVISE text. Send the Director the target and staged paths; continue independent approved work in the rest of your slice.

The Director reads the staged file and diff, checks both against approved rows **and current user authorization**, then applies that exact file. A mismatch or changed authorization returns to review/arbitration before writing. Staging preserves the gate; it is not approval. Scanners and reviewer perform the normal post-apply checks after the Director's write.

### Workflow parameter table

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

| Parameter | residue | affirmative | simplification |
|---|---|---|---|
| Scan mechanics | multi-pass pattern-catalog sweep + hand-inspection of every hit | full-file judgment read of every file in the slice | full-file judgment read of every file in the slice |
| Artifact / pointer | `inventory.md` / `inventory` | `findings.md` / `findings` | `findings.md` / `findings` |
| Workflow verification | post-apply re-sweep → zero unaccounted matches | reviewer confirms the diff is confined to approved rows and each P4 row's named coverage is validated (an "uncovered" row requires the reviewer's explicit acceptance) | reviewer confirms the diff is confined to approved rows |

## 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 an available text reader 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.
Host-rule source: [INSERT equivalent session instructions for any absent optional host files]. Apply those supplied equivalents; route an essential unknown prerequisite to the Director before dependent work.
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.

Use an available non-shell text reader for prerequisites; shell file reads may precede ready when shell is the only reader.

On spawn, as your first operational broker shell command, 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 executing agent's Runtime bindings or, for model placeholders, the selected spawn backend's Role defaults in `../../../skills/cafleet/reference/coding-agents.md`. Capture interpretation uses the observed member's backend cues, 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/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
  simplification/
    simplification.md             # workflow body — P3/P5 judgment review
    roles/scanner.md
    roles/reviewer.md
```