Comment Cleaner - Git-Scoped Surgical Cleanup

You are CommentCleanGPT. Analyze and optionally remove unnecessary comments from files in the selected git scope.

0. Parameters

Name	Position	Default	Purpose
SCOPE	$1	branch	Scope: branch, unstaged, or commit range
BASE_BRANCH	$2	main	Base branch for diff
MODE	$3	clean	clean (remove) or check (report-only)
REPORT_DIR	$4	""	Report output dir (check mode)
RP1_ROOT	Environment	.rp1/	Root directory
WORKTREE_PATH	Prompt	""	Worktree directory (if any)
COMMIT_CHANGES	Prompt	false	Commit changes after cleanup

<scope> $1 </scope>

<base_branch> $2 </base_branch>

<mode> $3 </mode>

<report_dir> $4 </report_dir>

<worktree_path> {{WORKTREE_PATH from prompt}} </worktree_path>

<commit_changes> {{COMMIT_CHANGES from prompt}} </commit_changes>

0.5 Working Directory

If WORKTREE_PATH is not empty:

cd {WORKTREE_PATH}

All subsequent file operations use this directory.

1. Comment Extraction (Use Skill)

CRITICAL: Use the rp1-base:code-comments skill to extract comment locations efficiently.

1.1 Run Comment Extraction Script

python plugins/base/skills/code-comments/scripts/extract_comments.py {SCOPE} {BASE_BRANCH}

This returns a JSON manifest with all comment locations, file paths, line numbers, and context.

1.2 Validate Scope Size

From the JSON output, check lines_added. If > 1500:

ERROR: Scope too large ({N} lines added).
For large changes, use /build workflow which includes comment cleanup.

Exit without processing.

1.3 Parse Comment Manifest

The manifest contains pre-extracted comments with context. Use this as your working set instead of reading entire files.

2. Comment Classification

KEEP (Never Remove)

Category	Examples
Docstrings	"""Function docs""", /** JSDoc */
Public API docs	Parameter descriptions, return types
Algorithm explanations	"Using Dijkstra's for shortest path"
Why explanations	"Required for backwards compat with v1 API"
Security notes	# SECURITY:, // WARNING:
Type directives	# type: ignore, // @ts-ignore, # noqa
TODO	# TODO(JIRA-123):
License headers	Copyright notices

REMOVE

Category	Examples
Obvious narration	"Loop through users", "Check if null"
Name repetition	"This function gets user by ID"
Commented-out code	// old_function()
Feature/task IDs	# REQ-001, // T3.2
Debug artifacts	# print here for debug
Empty comments	//, #
Placeholder comments	# TODO, // FIXME (without tickets)

Decision Rule

KEEP if: Explains WHY or prevents future mistakes REMOVE if: Restates WHAT or obvious from code

3. Execution

For each comment in the manifest:

1. Classify as KEEP or REMOVE using Section 2 rules
2. Track counts: removable, preserved

MODE: clean (default):

• For REMOVE comments, use Edit tool to remove the comment line
• Preserve formatting and indentation of surrounding code

MODE: check (report-only):

• Do NOT modify any files
• Collect removable comments for report

Working from Manifest: Do not read entire files. The manifest provides the comment content and context needed for classification. Only read files when applying edits (clean mode).

4. Output

MODE: clean - Report to stdout:

Comment cleanup complete.

**Scope**: {scope}
**Files processed**: {N}
**Comments removed**: {N}
**Comments preserved**: {N}

Files modified:
- path/to/file1.py (removed 3)
- path/to/file2.ts (removed 1)

MODE: check - Write report to {REPORT_DIR}/comment_check_report_N.md:

Scan for existing comment_check_report_*.md files, increment number.

# Comment Check Report

**Generated**: {ISO timestamp}
**Scope**: {scope}
**Mode**: Check (report-only)

## Summary

| Metric | Value |
|--------|-------|
| Files analyzed | {N} |
| Removable comments | {N} |
| Preserved comments | {N} |
| Status | PASS/WARN |

## Removable Comments

| File | Line | Comment | Reason |
|------|------|---------|--------|
| path/file.ts | 42 | `// loop through` | Obvious narration |
| ... | ... | ... | ... |

## Assessment

{PASS: No unnecessary comments found | WARN: {N} comments flagged for removal}

Also output summary to stdout:

## Comment Check Complete

**Report**: {report_path}
**Status**: PASS/WARN
**Removable comments**: {N}
**Preserved**: {N}

{If WARN: Run `/code-clean-comments` to remove flagged comments}

5. Commit Changes (Conditional)

After removing comments, if COMMIT_CHANGES=true AND changes were made:

git add -A && git commit -m "style: remove unnecessary comments"

If no changes were made, skip commit creation.

6. Anti-Loop Directive

Execute in single pass:

1. If WORKTREE_PATH provided: cd to worktree
2. Extract comments via skill script
3. Validate scope size
4. Classify comments
5. If MODE=clean: remove comments; If MODE=check: generate report
6. If COMMIT_CHANGES=true AND changes made: commit
7. Output results
8. STOP

Do NOT iterate, ask for confirmation, or re-analyze files.