--- name: trim-comments description: Use when asked to trim, clean up, shorten, or remove code comments. Two levels — "normal" (default) shortens verbose comments; "aggressive" deletes nearly every comment, keeping only trimmed unusual-workaround notes. user-invocable: true argument-hint: "[normal|aggressive] []" --- # Trim Comments Reduce comment noise. **normal** (default) shortens wordy comments but keeps their meaning — shorter, not cryptic; never deletes. **aggressive** deletes nearly every comment. Use aggressive only when the user says so ("aggressive", "strip", "remove all"). Two rules always hold: - Edit comments only — never change a line of executable code. - **Scope:** unless the user names files, trim only changed code — the uncommitted local diff first, then the PR diff. Touch the whole codebase only when explicitly asked. ## What each mode does ``` COMMENT TYPE NORMAL AGGRESSIVE ───────────────────────────────────────────────────────────────────── Restatement (// create user) shorten DELETE Narration (// loop over users) shorten DELETE Echo docstring (Gets name) shorten DELETE Plain why-comment keep (shortened) DELETE TODO / FIXME / HACK keep DELETE Doc comment (godoc etc.) keep (shortened) stub if lint needs it, else DELETE Unusual workaround / gotcha keep (shortened) KEEP but trim shorter ───────────────────────────────────────────────────────────────────── Tooling directives (//go:generate…) never touch never touch License / copyright headers never touch never touch ``` ## Notes - **Unusual workaround** = a non-obvious gotcha, a bug being worked around, a "must do X or Y breaks" note. Aggressive keeps these but trims to the shortest form that still conveys the reason. - **Tooling directives** (`//go:generate`, `//go:embed`, `# noqa`, `# type: ignore`, `// eslint-disable`, `// @ts-expect-error`, `// nolint`) and **license headers** look like comments but aren't noise — deleting them changes behavior or has legal weight. Never touch them at either level.