/squid-clean-docs

name: squid-clean-docs
disable-model-invocation: true
argument-hint: "[scope-path] (default: whole repo)"
description: >-
  Strip redundancy from prose — docs, READMEs, code comments, docstrings — keeping behaviour
  identical.

Clean docs — remove words, keep behaviour

You are the **cleaner**. You delete redundant prose — markdown docs, code comments, docstrings; you do **not** touch executable code. Zero behaviour diff is the contract — if a deletion could alter runtime, it is out of scope.

`$ARGUMENTS` is an optional scope path (`docs/`, `src/ingest/`). Empty means the whole repo.

When NOT to use — never touch these without explicit opt-in

| Excluded | Why | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `docs/adr/`, `docs/notes/` | ADRs are immutable historical records; notes are the user's. | | `CHANGELOG*`, `LICENSE*` | Append-only / legally load-bearing. | | `.github/` | Issue/PR templates and workflow files are functional surface, not reader prose. | | Generated + vendored trees (`node_modules/`, `.venv/`, `dist/`, `vendor/`, `*_pb2.py`) | Not authored; regenerated on build. | | Linter/type directives (`# noqa`, `# type: ignore`, `# pragma: no cover`) | These are code, not comments. | | Doctest examples (`>>>` blocks in docstrings) | Executable tests, not prose. |

Step 1 — Confirm scope

State the default exclusion list above, then ask (one round, `AskUserQuestion`): **what else is off-limits?** Do not scan until answered.

Step 2 — Apply the keep/delete test

Read every candidate file whole — never delete on a filename or a skim; a comment can only be judged next to the line it sits on.

**A comment or docstring survives only if it states something the code cannot.** A constraint, a non-obvious _why_, a limit, a workaround and its issue link. If it narrates _what_ the next line does, it is noise — delete it.

| Delete | Keep | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `# increment the counter` above `i += 1` | `# Chunk at 200 tokens — the embedding model truncates above 256.` | | A docstring restating the signature: `"""Takes a user_id and returns a User."""` | `"""Returns None for soft-deleted users; callers must handle it (see #412)."""` | | `# TODO: refactor this someday` (no owner, no issue) | `# TODO(#88): drop once the v1 endpoint is retired.` | | `# Fixed the bug where...` — history belongs in git | `# Retry 3×: the upstream API 502s under ~5% of cold starts.` |

**Docs:** a section dies when it duplicates a section that lives elsewhere. Keep exactly one home for each idea; replace the copy with a one-line cross-reference. A README that repeats `CONTRIBUTING.md`'s install steps loses them and links instead.

**Tasks/templates:** collapse repeated task files into one template plus the deltas; keep the template.

Step 3 — Plan of attack (the output artifact)

Print one table in chat. Do not write it to disk unless the user asks.

| File | What goes | Rule (Step 2) | ~Lines | | --------------------- | --------------------------------------------- | ----------------- | ------ | | `src/ingest/chunk.py` | 4 narrating comments, 1 signature docstring | restates code | −12 | | `README.md` | install section duplicating `CONTRIBUTING.md` | one home per idea | −18 |

Stop and wait for explicit approval. Do not edit before it.

Step 4 — Execute

Apply the approved plan. Commit one category at a time (`comments`, `docs`) so any revert is surgical.

Step 5 — Verify

Behaviour must be provably unchanged before hand-off:

• Test + lint suite green (`make pre-commit && make unit-tests`, or the project's equivalent) —

docstring deletions can break doctests and doc builds.

• `git diff --stat` touches only prose and docstrings — **no logic lines**.
• No broken internal links: every path, heading, or anchor you deleted or moved has no remaining

referrers.

Anything red: revert that commit, do not "fix forward".

Step 6 — Hand-off

Report lines removed per category and the verify result. If the README was reorganised, say what moved where.

Notes on shape

• **Removing beats rewriting.** Prefer deleting a paragraph to shortening it.
• If the caveman plugin is installed, run this first and `/caveman-compress` after — this decides what

exists, that compresses wording.