Trim Code Comments
Reduce comment noise without erasing context that future maintainers need.
Scope
Inspect changed source files by default. Inspect the whole repository only when the user explicitly asks for all comments. Skip generated files, vendored code, dependencies, lockfiles, snapshots, fixtures, and prose documentation.
Classification
Remove a comment only when the adjacent code expresses the same fact just as clearly. Typical candidates narrate assignments, loops, branches, calls, returns, or obvious names.
Keep comments that carry information the code cannot express directly:
- rationale, trade-offs, invariants, or failure semantics;
- security boundaries, threat assumptions, or fail-open/fail-closed behavior;
- compatibility constraints, workarounds, protocol rules, RFCs, issues, or TODO context;
- architecture, deployment, concurrency, ordering, performance, or lifecycle constraints;
- public API documentation required by the language or repository;
- lint, formatter, coverage, build, code-generation, or type-checker directives;
- non-obvious examples, units, ownership, or data provenance.
When uncertain, keep the comment.
Workflow
- Read repository instructions and identify the source diff.
- Identify high-confidence candidates within the requested scope.
- Use adjacent code; consult history when it helps establish rationale.
- For an audit, report the comment, path and reason.
- When removal is requested, perform the clear removals within that authorization. Ask only when a candidate has unresolved meaning or ownership.
- Remove only approved comments. Do not rewrite useful comments merely to create activity.
- Run the cheapest formatter, lint, typecheck, or compile check that can catch a damaged directive or syntax boundary.
Output
Order candidates from most redundant to least. Distinguish remove from keep; include useful comments when they are close calls so the user can see why they survived.
Provenance
This independent workflow was inspired by Luke Berry's remove-dumb-comments skill. See the standalone trim-code-comments repository for attribution and implementation differences.
1---2name: trim-code-comments3description: Review source comments and remove low-value comments that only narrate visible code while preserving rationale, constraints, safety context, public documentation, and tooling directives. Use when asked to trim code comments or remove dumb, redundant, obvious, excessive, or AI-generated comments. Do not run automatically after implementation.4---56# Trim Code Comments78Reduce comment noise without erasing context that future maintainers need.910## Scope1112Inspect changed source files by default. Inspect the whole repository only when the user explicitly asks for all comments. Skip generated files, vendored code, dependencies, lockfiles, snapshots, fixtures, and prose documentation.1314## Classification1516Remove a comment only when the adjacent code expresses the same fact just as clearly. Typical candidates narrate assignments, loops, branches, calls, returns, or obvious names.1718Keep comments that carry information the code cannot express directly:1920- rationale, trade-offs, invariants, or failure semantics;21- security boundaries, threat assumptions, or fail-open/fail-closed behavior;22- compatibility constraints, workarounds, protocol rules, RFCs, issues, or TODO context;23- architecture, deployment, concurrency, ordering, performance, or lifecycle constraints;24- public API documentation required by the language or repository;25- lint, formatter, coverage, build, code-generation, or type-checker directives;26- non-obvious examples, units, ownership, or data provenance.2728When uncertain, keep the comment.2930## Workflow31321. Read repository instructions and identify the source diff.332. Identify high-confidence candidates within the requested scope.343. Use adjacent code; consult history when it helps establish rationale.354. For an audit, report the comment, path and reason.365. When removal is requested, perform the clear removals within that authorization. Ask only when a candidate has unresolved meaning or ownership.376. Remove only approved comments. Do not rewrite useful comments merely to create activity.387. Run the cheapest formatter, lint, typecheck, or compile check that can catch a damaged directive or syntax boundary.3940## Output4142Order candidates from most redundant to least. Distinguish `remove` from `keep`; include useful comments when they are close calls so the user can see why they survived.4344## Provenance4546This independent workflow was inspired by Luke Berry's [`remove-dumb-comments`](https://github.com/LukeberryPi/skills/tree/main/skills/remove-dumb-comments) skill. See the standalone [`trim-code-comments`](https://github.com/badmuriss/trim-code-comments) repository for attribution and implementation differences.
badmuriss