Add a revise-comments skill for applying comment-discipline rules

[williamthorsen]

Problem

#642 codified a comment-discipline rule for new code, but there is no tool to apply the rule to existing comments. The user just spent 30 minutes hand-cleaning comments in another session, and a backlog of historical comments in existing files would benefit from the same audit. Hand-applying the audit checklist file by file is repetitive work that fits the rule's deterministic shape.

Context

The rule has been canonicalized in _data/comment-discipline.md, with the audit checklist factored into _partials/comment-audit-checklist.md and consumed by code-patterns, testing-conventions, and code-simplification-reviewer. What is missing is an author-side tool that applies the same audit to a target file set in a single command.

Decision shape (settled during the #642 wrap-up): build as a skill, not a subagent. A skill composes upward (a subagent can declare it in skills: later if fire-and-forget dispatch becomes worthwhile) and runs in the main agent's context, so the user can review the per-comment decisions via git diff after the edits land. Subagent dispatch can be added as a thin wrapper if usage signals call for it.

Proposed solution

Add a user-invocable revise-comments skill that loads _data/comment-discipline.md at start, transcludes the audit checklist partial, and applies the rules to a target file set. The skill applies edits in place per file and emits a per-file summary at the end, classifying each comment decision as kept, deleted, or rewritten with the rule that applied.

The skill is single-command by design. The default target is the set of files committed on the current branch relative to the default branch, resolved through a single git diff --name-only call that matches the convention used by other branch-scope skills. The typical workflow is /revise-comments with no arguments after a feature has been committed. Explicit file or directory arguments are accepted for cleaning up legacy code or auditing uncommitted work in the working tree; /revise-comments . covers the full working tree, with .gitignored trees excluded by the directory-traversal rules. A --dry-run flag produces the summary report without applying edits, which subsumes the triage mode previously listed as a nice-to-have.

The skill respects both existing carve-outs (test comments with legitimate reasons, tight eslint-disable rationales) using path heuristics for test files and prefix detection for eslint-disable lines.

When the agent is genuinely uncertain about a comment (borderline carve-out cases, ambiguous file headers), it pauses and asks. The default action is to act, not to ask.

The verification surface lives in the SKILL.md body: it transcludes the existing audit checklist partial and embeds one compact worked example demonstrating multi-comment file revision and the per-file summary output. No separate fixtures directory is introduced.

Acceptance criteria

Must have

• A user-invocable revise-comments skill exists at packages/agents/content/skills/revise-comments/ that, given a target file set, applies the audit rules in _data/comment-discipline.md and edits comments in place.
• The skill loads _data/comment-discipline.md at start and transcludes the audit checklist partial. The rule is not re-derived inside the skill body.
• The skill respects both carve-outs (test comments with legitimate reasons, tight eslint-disable rationales).
• The skill works on files changed on the current branch (default target) and on explicit file or directory arguments.
• A --dry-run mode produces a per-file summary without editing files.
• The skill emits a final per-file summary at the end of every run, classifying each comment as kept, deleted, or rewritten with the rule that applied.
• Documentation, help text, and the changelog are updated to reflect the new skill.

Should have

• Directory targets respect .gitignore, so node_modules/, dist/, and other non-authored trees stay out of the set.

Nice to have

• A subagent wrapper for fire-and-forget dispatch (deferred; add only when usage signals call for it).

Related

• Foundation: Add comment discipline to agent guidance and review pipeline #642 (closed, merged via #642 Add comment discipline to agent guidance and review pipeline #659), established the rule this skill applies.