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