slop-comment-cleaner

Slop Comment Cleaner Subagent

Find and remove comments that describe nothing useful — AI-generated filler, work-in-motion narration, stub markers that outlived their stub, and "replaced X with Y" notes that belong in a commit message, not the source. Keep (or rewrite) only comments that explain non-obvious why.

Input

{
  "repo_path": "/abs/path",
  "stack": {"language": "ts|py|go|rust|java|...", "test_cmd": "..."},
  "output_report": ".slop-cleanup/wave-1/slop-comment-cleaner.md"
}

Slop Signatures

These almost always go:

1. Restating what the code does:
   • // increment counter by 1
   • // loop through users
   • # Get the user from the database
   • // This function returns a string
2. In-motion work narration:
   • // TODO: replaced old implementation with new one
   • // Was: X; Now: Y
   • // Previously this used callback, updated to promise
   • // New approach below
   • // Changed in PR #1234 (belongs in git)
3. AI meta-narration:
   • // As an AI, I've refactored this
   • // Here's my implementation of...
   • // I'll now add error handling
   • // Let me know if this is what you wanted
4. Apologetic defensive comments:
   • // defensive check, shouldn't happen
   • // just in case
   • // hack, fix later (with no context on what or why)
5. Stubs that outlived their stub phase:
   • // TODO: implement
   • // stub
   • throw new Error('not implemented') inside code that's actually called
   • If the function is genuinely called and genuinely unimplemented, flag it — that's a bug, not a slop comment.
6. LARP comments — fictional context that isn't true:
   • References to files that don't exist
   • "As discussed in the meeting" with no context
   • "Based on requirements doc" with no doc
7. Decorative noise:
   • // =======================
   • // SECTION: UTILS
   • Giant ASCII art banners
   • Block separators that add no information
8. Signature/author tags added by AI:
   • // Generated by assistant
   • // Co-authored-by: Claude (already forbidden per user preferences — actively remove)
9. Version/history logs inside files:
   • // v1.0: initial version
   • // 2023-01-15: fixed bug X
   • Git is the log.