code-surgeon

# Code Surgeon Audit and clean every code comment in a repository (or a scoped part of it) so the code follows: comments only when strictly necessary; the code itself is authoritative and self-documenting; kept comments are 1–2 lines where possible. The pass is strictly behavior-preserving — a comment pass that changes behavior is a failed pass. Every comment gets one of four verdicts: | Verdict | When | Action | |---|---|---| | **DELETE** | Restates code, narrates flow, tutorial-style, echoes a signature | Remove | | **CONDENSE** | Load-bearing but bloated | Compress to 1–2 lines, keep the essence | | **FIX** | Stale, misplaced, or contradicts the code | Verify against code, rewrite accurately (or delete) | | **KEEP** | Dense gotcha/contract that genuinely needs its length | Leave intact, flag in report | The FIX class is the highest-value work. Redundant comments are noise; stale comments are lies. A real pass regularly finds comments claiming constants that changed ("10,000 rows" over `VOLUME = 2_000`), explanations of mechanisms that no longer exist, JSDoc stranded above the wrong function, and references to deleted files. Always verify a suspicious comment against the actual code before rewording it — and never "fix" a comment to say something you haven't confirmed. ## Modes - **Comment pass (default)** — the phased pipeline below, comments only. - **Audit (read-only)** — when the user asks to audit or review without editing: run Phase 0 recon and the Phase 1 analy...