Initial commit

shavakan/cleanup-comments.md

@@ -0,0 +1,158 @@
+---
+description: Remove obvious comments, commented code, outdated TODOs - keep 'why' explanations
+---
+
+# Remove Comment Noise
+
+Remove comments that add zero value. Code should be self-documenting. Keep comments that explain "why" not "what".
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. Backup branch created automatically
+3. Test validation after each change category (if tests exist)
+
+**Run prerequisite check:**
+
+```bash
+PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
+
+if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
+  echo "ERROR: Invalid plugin root path"
+  exit 1
+fi
+
+PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
+if [[ ! -f "$PREREQ_SCRIPT" ]]; then
+  echo "ERROR: Prerequisites script not found"
+  exit 1
+fi
+
+PREREQ_OUTPUT=$(mktemp)
+if "$PREREQ_SCRIPT" --skip-tests > "$PREREQ_OUTPUT" 2>&1; then
+  source "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+else
+  cat "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+  exit 1
+fi
+```
+
+This exports: `TEST_CMD`, `BACKUP_BRANCH`, `LOG_FILE`
+
+---
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Identify and remove comment noise across the codebase while preserving valuable "why" explanations.
+
+### Remove These
+
+**Obvious comments** - Repeat what code does ("increment counter" above `count++`)
+
+**Commented code blocks** - 5+ consecutive commented lines with code syntax (belongs in git history)
+
+**Outdated TODOs/FIXMEs** - >1 year old or already completed (check git blame)
+
+**Redundant documentation** - JSDoc/docstrings that add no value beyond signature (`@param user The user`)
+
+**Visual separators** - ASCII art, "end of section" markers (use file structure instead)
+
+### Preserve These
+
+**Non-obvious "why" explanations** - Why this approach vs alternatives
+
+**Workarounds** - Performance trade-offs, security considerations, edge cases
+
+**Hacks with justification** - Browser quirks, API limitations, temporary fixes with context
+
+---
+
+## Execution
+
+### Phase 1: Identify Comment Noise
+
+Scan codebase for all five categories. For each finding, capture:
+- Location (file:line or range)
+- Comment content and surrounding code
+- Why it's noise vs valuable
+
+Present findings grouped by category with counts. Include examples of valuable comments you're preserving to demonstrate understanding.
+
+Identify refactoring opportunities where improving code clarity (better names, extracted functions) would eliminate the need for explanatory comments.
+
+**Gate**: User must review findings before removal.
+
+### Phase 2: Confirm Scope
+
+Present findings to user:
+```
+Remove comment noise?
+
+□ Safest - Visual separators + obvious comments
+□ Low risk - Commented code blocks + redundant docs
+□ Needs review - Outdated TODOs (might still be relevant)
+□ Custom - Select specific categories
+□ Cancel
+```
+
+**Gate**: Get user approval on which categories to remove.
+
+### Phase 3: Execute Removals
+
+For each approved category:
+
+1. Consider refactoring first: If comment explains complex logic, can you make the code self-documenting instead?
+
+2. Remove comments: Edit files safely. Process one category completely before starting next.
+
+3. Test and commit: Run `$TEST_CMD` after each category. If tests pass, commit with message explaining what was removed. If tests fail, rollback and report which removal caused the issue.
+
+**Gate**: Tests must pass before proceeding to next category.
+
+### Phase 4: Report Results
+
+Summarize what was removed (counts per category), what was preserved, code improvements made, and impact (lines reduced, readability improved).
+
+Delete the backup branch after successful completion:
+```bash
+git branch -D "$BACKUP_BRANCH"
+```
+
+---
+
+## Safety Constraints
+
+**CRITICAL:**
+- One category at a time with test validation between each
+- Commit granularly - each category gets its own commit
+- When in doubt, preserve the comment
+- If comment explains complex code, refactor the code instead of removing comment
+- Never remove comments that justify non-obvious technical decisions
+- Test failure → rollback immediately, investigate before retrying
+
+**If tests fail**: Rollback with `git checkout . && git clean -fd`, identify which specific removal broke tests, decide whether to skip that item or investigate further.
+
+---
+
+## After Cleanup
+
+**Review with code-reviewer agent before pushing:**
+
+Use `shavakan-agents:code-reviewer` to verify changes don't introduce issues.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:cleanup` - Full repository audit
+- `/shavakan-commands:cleanup-dead-code` - Remove unused code
+- `/shavakan-commands:cleanup-deps` - Clean dependencies