comment-purge

# Comment Purge Delete unnecessary comments rather than rewrite them. Keep protected comments and unresolved warnings. Fix exposed code problems only within the authorized scope; comment cleanup alone does not authorize behavior changes. ## Scope Use the caller's files or diff. Otherwise use the current diff against the base branch, default `main`, including staged and unstaged working-tree changes. If no usable base exists, ask for one or an explicit scope. Do not widen a diff to whole files or widen the scope to other instances of a problem. Read repository rules and record the existing changes before editing. Preserve pre-existing user work; stop and ask if edits conflict. No automatic Git writes. ## Deletion Rules - Delete narration, section banners, commented-out dead code, and explanations shown to be redundant, false, or obsolete. Keep a workaround's explanation until evidence shows the constraint is obsolete or an authorized fix removes it. - Keep legal and license notices and doc comments that define public API contracts. - Keep verified non-obvious constraints from an external dependency, platform, vendor, or protocol that this project cannot change. - Keep issue or RFC links that explain constraints code cannot express. - Preserve formatting directives and functional build, compiler, and tool directives. Comment syntax does not make an instruction safe to delete. Diagnostic suppressions follow the separate rule below. - Inspect every scoped suppression, including `eslint-disable`, `@ts-ignore`, and `@ts-expect-error`. Read the rule and evidence. Keep false-positive, faulty-rule, or style-only suppressions. Correctness or safety suppressions need removal and a root-cause fix, not a replacement that hides check failures. - Investigate `IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications. Trace nearby code, exact symbols, callers, tests, and available issue or dependency evidence. A claimed external constraint needs proof that it still applies on a live path. Do not depend on a named skill or command. - Preserve ambiguous warnings when the evidence does not establish that removal is safe. Report the missing evidence or proposed code change. These deletion rules never override protected directives or legal notices. - Use neutral action flags such as `Refactor`, `Fix suppression`, or `Unenforced constraint`. Name the exact in-scope symbol, evidence, and needed change. Do not invent defects or label intentional behavior as faulty. ## Workflow 1. Use an available independent reviewer when supported. Pass the exact scope, existing-change baseline, and all deletion and review rules in this skill. Otherwise use separate comment-edit and review passes yourself. The initial reviewer edits comments only, never application code, and reports touched files, deleted comment count, action flags with evidence, and skips. 2. The parent reviews the report and diff. Reject application-code edits, scope escapes, protected deletions, unsupported flags, and missed suppressions. Check evidence for deleted warnings and restore any removed without sufficient evidence. Keep explanations while their constraint or refactor is unresolved. Delete refuted warnings only when the evidence establishes safe removal. Preserve valid action flags for internal surprises. 3. For a rejected pass, undo only that pass's rejected edits, preserving the baseline and concurrent user changes. Name the failure and allow one corrected pass. If it is rejected again, remove its rejected edits, report the work open, and stop with failure. Ask if edits cannot be separated safely. 4. Within the authorized scope, the parent fixes accepted trivial causes: remove a dead path, drop an unused parameter, or use the correct API. For larger refactors, first sketch the proposed structure using surrounding code, then make the smallest in-scope root-cause fix. Remove the named workarounds, not just their explanations. Do not add symptom guards. If a cause is outside scope, make only a sound in-scope fix and report the remaining work; do not widen scope to finish it. 5. Retain proven external constraint comments. For unprotected constraints such as wording freezes or approval warnings, offer the cheapest in-scope type, runtime check, test, or CI rule. Ask before encoding it; unattended execution needs explicit caller pre-approval, never implied consent. If approved, encode and verify the constraint before deleting a now-redundant comment. Otherwise preserve the warning and report the remaining unenforced constraint. Sketch out-of-scope work only. 6. After the final edit, run required repository formatting, lint, build/typecheck, and relevant test commands from repository instructions and CI configuration. Review the final diff for scope, protected comments, directives, and user work. Fix in-scope failures; report failed, unavailable, or unknown required checks as blockers. Do not claim successful cleanup while required checks fail or remain unverified, or while correctness or safety findings remain unresolved. ## Report Report touched files, deleted comment count, restored comments with exceptions, corrected passes, refactor sketches, fixes, encoding offers and approvals, completed encodings, unenforced constraints, skips, and other open work. Include check commands and results. Distinguish completed cleanup from blockers.