Cleanup Stale Code

Overview

Two-phase workflow for cleaning two related kinds of codebase drift: comments (stale migration notes, low-value narration, expired bridge comments) and tests (over-coupled assertions, mock-path style debt, deprecated-API regression tests). Both share the same shape: produce a prioritized inventory, then batch-execute by priority. The key insight is that analysis and execution are separate steps with different failure modes — do not merge them.

When to Use

• "stale comments / comment cleanup / remove migration notes" — see Section A
• "test cleanup / delete test cases / evaluate tests / remove dead tests" — see Section B
• A codebase has accumulated phased implementation markers, migration notes, obvious-code comments, or failing tests, deprecated-API regression tests, and mock-path style debt over many iterations

When NOT to Use

• Adding new doc comments or improving comment style
• Adding new test coverage
• Auditing one specific file manually
• Change is ≤3 lines (do it inline)