# Squid Clean Docs

> Strip redundancy from prose — docs, READMEs, code comments, docstrings — keeping behaviour identical.

- Skill: `iusztinpaul/squid-clean-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iusztinpaul/squid-clean-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iusztinpaul/squid-clean-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iusztinpaul (https://skillmd.com/u/iusztinpaul)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iusztinpaul/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

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