SamElhagDev Trim Comments
Overview
Cuts comments to what a careful human would write. Only comment and docstring lines change.
Scope
- Run
git status --shortandgit diff -U0 HEAD. - Pick the scope:
- Request says "across the repo" or similar: every file from
git ls-files - Otherwise: comments on lines added or changed in
git diff -U0 HEAD, plus all comments in untracked files. A comment block is in scope when any of its lines is.
- Request says "across the repo" or similar: every file from
- Leave out
.specify/,wwwroot/lib/,node_modules/,Migrations/, and generated or minified files. - Count the comment and docstring lines in scope. If the count is 0 and the request wasn't repo-wide, reply
Nothing to trim in uncommitted changes. Trim the whole repo instead?and stop.
What each comment becomes
| Comment | Becomes |
|---|---|
| Restates what the code shows, or tells its history ("previously", "now uses", "before this existed") | Removed |
| Explains why: a reason, constraint, pitfall, or workaround | Kept at 1 or 2 lines, on the line it explains |
| Wrong about what the code does | Corrected or removed, and reported |
Docstring or /// block |
One line: """...""" or /// <summary>...</summary>. Its why moves to a comment on the line it explains, or above the first body line when it covers the whole function. Removed when the line would only repeat the name, unless that leaves the body empty; then the one line stays |
Banner like # ── Setup ── or /* ===== FONTS ===== */ |
Plain label: # Setup, /* Fonts */ |
| Em-dash | ;, :, . or , |
Spec Kit IDs (T032, US3, FR-008, SC-007, Principle I) |
ID removed, sentence kept; the whole comment goes when it only tracks a task |
Functional: # noqa, # type: ignore, #region, // <auto-generated>, /// <inheritdoc />, shebang, encoding line, license header |
Unchanged |
| Commented-out code | Unchanged, and reported |
Checks
- Python files changed:
python -m compileall -q <files>, thenpython -m pytest -qwhen the repo has tests. .NET files changed:dotnet build. - Read the resulting
git diff: only comment text, docstrings, and blank lines differ. Put back any code that changed.
The reply
Exactly these lines, in order:
Trimmed comments in <n> files: <before> to <after> comment lines.- Only when a wrong comment was corrected or removed:
Fixed wrong comments:then- <file>:<line> <what it claimed; what the code does> - Only when commented-out code is in scope:
Commented-out code left in place:then- <file>:<line> Checks: <results>(e.g.compileall clean, tests pass), orChecks: none found; review the diff.
Changes stay unstaged and uncommitted.