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:

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:

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