Trim Comments

/lean:trim-comments

Judge every comment and docstring in the target files against ../../references/comment-policy.md, then delete or rewrite the ones that fail. Edits in place and prints a diff. Never commits, never pushes, never requires a clean tree.

Confirm before the first edit

This skill deletes code the user did not ask you to touch, and it can be routed to from a passing remark about comments. Present the classification and get an explicit yes through AskUserQuestion before any Edit.

No exceptions: not for a single comment, not for a file the user just named, not under --all. --diff-only is the way to skip the edit, not the confirmation.

$ARGUMENTS

• paths/globs — files to audit, resolved through git ls-files -- <glob> when tracked, else as literal paths.
• --staged — audit what is staged rather than the branch diff.
• --all — audit every tracked file. Expect a large diff; say so before confirming.
• --diff-only — classify and show what would change, edit nothing.

With no paths, the target set is the files this branch changed.

Steps

1. Resolve targets. With paths, expand them. With --all, take git ls-files. With --staged, take the staged names:

   $ git diff --name-only --cached --diff-filter=d
   

   Otherwise find the trunk ref (git rev-parse --abbrev-ref origin/HEAD, falling back to the repo's default branch) and take its merge base:

   $ git merge-base HEAD origin/HEAD
   

   Then take the names changed since it:

   $ git diff --name-only --diff-filter=d <merge-base>
   

   Keep source files; drop lockfiles, generated output, and vendored trees. Reject an empty target set with a clear message rather than widening the scope on your own.

2. Load the policy and voice. Read ../../references/comment-policy.md, then ./AGENTS.md and ./CLAUDE.md. Where the host project sets its own comment rules, those govern.

3. Classify. Every comment and docstring in range gets one verdict — keep, rewrite, or delete — and a failing gate by name for anything not kept. A verdict you cannot attach to a gate is a keep.

   Read the surrounding code before judging. A comment that looks like narration but pins an invariant is a keep, and the loss gate is what protects it.

4. Preview and confirm. Show each rewrite as old and new text, and each deletion with the code it sat above, grouped by file. Confirm through AskUserQuestion. Skip only for --diff-only.

5. Apply. Use Edit. Rewrites are concrete and shorter than what they replace. Do not touch the code itself; a comment that is wrong because the code is wrong is a finding to report, not to fix here.

6. Diff. Print git diff -- <targets>.

7. Report and hand off. Give the counts kept, rewritten, and deleted, and name anything skipped and why. Then offer next steps through AskUserQuestion: commit with /commit, tighten the prose too with /lean:tighten, or discard — review the printed diff first, since git checkout -- <file> resets the whole file to HEAD and drops any other uncommitted work in it.

What this does not do

• Commit or push — that is /commit.
• Edit code, only its comments.
• Rewrite prose files — that is /lean:tighten.
• Rewrite history — that is /pr:deslop.
• Add missing comments. Absence is not a finding here.