gs-find-bad-comments

Installation
SKILL.md

Find every comment that should be removed, and report it. Change no file.

This pass is strict on purpose. A comment is guilty until it fits the keep list. Code that needs a comment to be understood is reported too, as code to reshape.

0. Pick the scope

The user names the scope in prose. With files or a directory, judge every comment in them. With a diff, or with nothing named, judge only the comments and suppressions the diff adds or changes. With nothing named, the diff is the current one against the default branch, including the working tree, and you tell the user that is the scope. Find the default branch with git symbolic-ref --short refs/remotes/origin/HEAD, then git remote show origin, then main.

1. Judge each comment against the keep list

Read every file in scope from disk. Judge each comment against this list alone, not against what you remember of the session.

Only these comments are kept:

  • Legal or license headers.
  • Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape.
  • // prettier-ignore, and a lint suppression whose rule is faulty, pedantic, or style-only.
  • Doc comments that define a public API contract.
  • Issue or RFC links that explain a constraint code cannot express.
Installs
3
First Seen
2 days ago