feat(cozystack): add comment-audit and comment-trim skills

[Timofei Larkin (lllamnyp)]

What

Adds two skills to the cozystack plugin, invoked as /cozystack:comment-audit and /cozystack:comment-trim. Plugin version 1.15.1 → 1.16.0 (additive features).

Both are repository-agnostic — they carry no Cozystack-specific assumptions and are usable on any codebase, in the same way linstor:recover is useful on any cluster running LINSTOR.

Why

Reviews regularly stall on code comments that argue instead of inform: product rationale, before/after narrative, incident retelling, and the same argument restated in a package doc, again at the call site, and again in the PR description. The two skills split that work into the classification half and the editing half, so the second never runs on comments the first has not judged.

/cozystack:comment-audit

Classifies every comment a change added against one rule — a comment earns its place when it tells the reader something the code cannot (mechanism, ordering constraint, aliasing hazard, "why not the obvious approach", silent-failure warning) and is design-doc prose when it argues (product rationale, evolution narrative, incident retelling, UX reasoning, editorializing, restating the line below).

Four phases: scope to the diff, classify each added block in full, sweep for the same argument appearing at several sites, build the keep list. Output is a fixed report shape with line anchors and quoted text, so a reviewer can act without re-reading the diff.

Reports only, modifies nothing — read-only end to end, so there is nothing to gate.

Notable anti-goals it enforces on itself: never forecast an aggregate line count (the estimate runs high and then measures the work); don't judge by comment density (if the surrounding files already carry prose, the local average is the thing being corrected); don't audit generated files or operator-facing config docs like values.yaml and chart templates, where verbosity is usually correct.

/cozystack:comment-trim

Applies an audit. The failure it exists to prevent is compressing an essay and calling it deleted — length was never the complaint, so it works claim by claim rather than block by block: a cut claim must be absent afterwards, a kept claim keeps saying what it said. Where a comment existed to keep code and a design doc in sync, it leaves a pointer to the section rather than a paraphrase, because a paraphrase is a second copy that will drift.

Ships scripts/comments-only.py, a string-aware comment stripper that compares both sides of the diff with comments removed and exits 0 (no code moved) / 1 (code moved, files named) / 2 (unrecognised language, needs a human). URLs inside literals, Go raw strings, rune literals and Rust lifetimes do not fool it. Verification is two steps: the script, then the project's build/lint/tests for the touched packages only.

Leaves changes in the working tree; does not stage, commit, push, or comment on a PR. Gate-and-confirm as usual: read-only lookups run freely, the file-and-claim list is stated before the first edit, and a commit is a separate ask.

Conformance to repo conventions

• Frontmatter: name, trigger-oriented description, argument-hint.
• Body opens with # cozystack:<name>, carries the explicit does / does-not-do paragraph, the gate-and-confirm framing, the cozystack:<name> self-naming instruction, phase-transition announcements, and the operator-natural-language note (report prose follows the operator's language; quoted comment text, paths and identifiers stay verbatim).
• Registered in plugins/cozystack/.claude-plugin/plugin.json and the plugins[] entry in .claude-plugin/marketplace.json, in the established name (one-line summary) pattern, plus the trailing "Invoked as …" list.
• README.md skills table and repository-layout listing updated (eleven → thirteen skills). The CLAUDE.md skill enumeration was stale at ten and is now correct at thirteen.

Verification

• bash tools/check-refs.sh — all five checks pass.
• jq parses both manifests.
• comments-only.py smoke-tested; exits 0 on an unchanged file.

Review focus

These skills were originally written for private work and have been genericized for publication. The worked examples, the incident-retelling and product-rationale samples, and the design-doc pointer target (docs/design/upload.md) are all invented placeholders in a neutral upload/retry and cache-key domain. Worth a cold read of both SKILL.md files for anything that still assumes a particular codebase.

Opened as a draft for that reason.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}