commentsaudit

# Comments Audit Find low-value comments and act on them. A deterministic Shiki pass extracts comments over TextMate grammars, the scope selects which to judge, a fan-out of Claude Code agents judges each against the owner's comment model, and a deterministic applier writes the changes to a branch. The judge returns one of three actions per comment: `keep` (it earns its place), `trim` (it carries no fact, delete or shorten it), or `rewrite` (it carries a real fact under AI voice, strip the voice and keep the fact). A comment earns its place when it adds information not readily available in the adjacent code. See [`judge/prompt.md`](../../judge/prompt.md) for the full model and carve-outs. The pipeline is three steps: `preflight` (extract, rank, build the job), the Workflow tool (judge), and `apply` (write the trims or report them). ## Scope and Flags Two scopes run the same pipeline. The flags select scope and narrow it: - Default, `--base <ref>`, `--mr <iid>`: diff scope. Judges the comments a change introduced. Default is the working tree (staged plus unstaged). `--base main` is the merge-base with a ref. `--mr <iid>` is a GitLab merge request over `glab`. - `--all`: repo scope. Judges every tracked code file's comments. - `--path <glob>`: narrow either scope to matching paths. Repeatable. Prefer it on a first `--all` run on a large repo to cap the agent count. - `--sort lines|chars|score` (default `score`): rank by intrinsic comment complexity so the longest, ...