skills.rest
peachest
peachestCOMMUNITY
Explore all skills by this author →
GitHub

comment-trim

Detect and trim redundant Go doc comments that exceed function body length.

Updated Jul 20, 2026
Search Tags:#git#static analysis#code review#pull request#refactoring#go#comment cleanup
One-click install
npx skills add https://github.com/peachest/skills --skill comment-trim-peachest
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: comment-trim
Source: https://github.com/peachest/skills/tree/main/in-progress/comment-trim
Command: npx skills add https://github.com/peachest/skills --skill comment-trim-peachest

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? AI-authored and PR-introduced Go code often ships with doc comments longer than the code itself, restating signatures, duplicating guidance, or recording expired facts. This Skill runs the full discover→classify→edit→verify loop so the output is a cleaned-up diff, not just an audit report. ## Core Features & Use Cases - Automated scanning: A Python scanner flags Go functions whose doc comment is as long as or longer than the body, with an adjustable ratio threshold. - Rule-based classification: Four redundancy classes (restates code, duplicated elsewhere, narrates the obvious, expired facts) plus load-bearing patterns that must be kept regardless of length. - End-to-end editing: Applies comment-only edits, sweeps unresolvable references, verifies with build/test/lint, and folds changes back via git fixup and autosquash. - Use Case: Before pushing a PR that introduced new Go files with verbose doc comments, run the scan, rule on each flagged comment, trim in place, and fold the result into the unpushed commit. ## Quick Start Scan the Go files my PR introduced, trim the redundant doc comments in place, and verify the build still passes.

Frequently Asked Questions about comment-trim

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find Go functions with comments longer than the code?▼

Run the scan script with the target files or directories: python3 scripts/scan.py <files-or-dirs>. It prints comment and body line counts per function and flags candidates with a warning marker. Use --ratio 0.8 to widen the detection net.

How to decide which code comments to delete during review?▼

Classify each flagged comment into four redundancy classes: restates the signature or body, duplicated elsewhere, narrates the obvious, or expired facts. Keep load-bearing content like issue references, truth tables, and anti-simplification trap notes regardless of length.

Does the comment scanner work with languages other than Go?▼

The scanner is Go-specific, detecting functions via the ^func pattern and brace balancing. The classification rules transfer to other languages, but a per-language function matcher is needed first. For YAML, shell, or helm templates, run the ruling pass manually.

Should I clean up redundant comments in existing legacy code?▼

No, the scope discipline limits edits to files the PR introduces or heavily rewrites. Existing code with the same smell stays untouched and is flagged to the user as a separate cleanup task.

How are trimmed comments folded back into git history?▼

For files in an unpushed commit, fold via git commit --fixup <sha> followed by git rebase -i --autosquash <base>. For already-pushed heads, ask the user whether to use a separate docs or style commit versus a history rewrite.

Related Skills

Explore More Software Engineering Skills→
ngx-signal-formsngx-signal-forms
3

code-reviewer

Review unstaged diffs and recent commits against repository guidelines.

Official
Advanced
LiozShorLiozShor
2

git-ship

Validate Git branches, diffs, and commit messages before pushing or merging.

Community
Advanced
GuyErreichGuyErreich

code-quality

Enforce ESLint and TypeScript standards to fix lint errors and typing issues.

Community
Advanced
raybargasraybargas

Global Commenting

Enforces uniform, standard-based commenting across entire codebases and integrates with linters and static analysis tools for automated checks.

Community
Basic