iusztinpaul/squid/squid-clean-docs

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

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.

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.

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.

When run unattended (a scheduled routine), also send that report with PushNotification — nobody reads the session.

Notes on shape

• Removing beats rewriting. Prefer deleting a paragraph to shortening it.