cleanup-comments.md

Goal

Clean the repository of unnecessary comments and produce a Markdown check-list for manual review of any comments that remain.

Execution Modes

Single Agent Mode (Default)

Follow the high-level algorithm below without any parallelization.

Parallel Agent Mode

When multiple agents are available (N agents, where N is specified by the user), follow the parallel execution instructions to distribute work efficiently.

High-level Algorithm (Single Agent)

1. Recursively scan every file in the project, skipping service folders (node_modules, .git, build/cache/output directories, etc.).

2. For each code file found (*.js, *.ts, *.jsx, *.tsx, *.mjs, *.cjs, *.vue, *.svelte, …): 2.1 Open the file and delete: • any single-line // or multi-line /* … */ comments that merely restate what the code already makes obvious
   (e.g. // increment counter right above counter++);
   • every public JSDoc block /** … */ (this is an internal app, not a reusable library). 2.2 Save the file with the edits applied. 2.3 Determine whether any comments are still present. • If none remain → mark the file as done ✔︎.
   • If some remain → leave the file open ✘ and collect details: line number ➜ comment text ➜ a brief note of why it was kept (e.g. a magic constant, a tricky algorithm, a workaround).

3. Generate COMMENT_CLEANUP_CHECKLIST.md in the repo root with this structure:

   ## Comment-cleanup checklist
   
   - [x] src/utils/math.ts
   - [x] src/config/index.ts
   - [ ] src/components/Chart/LineChart.tsx  
     - `42`: `// MAX_RETRIES = 7  // chosen experimentally, see issue #123`  
       > Kept because the meaning of "7" is documented nowhere else.  
     - `113`: `// 🐛 FIXME – remove fallback once API v3 is live`  
       > Reminder about technical debt.
   - [x] server/routes/auth.ts
   ...

Parallel Execution Instructions

Prerequisites

• Determine the number of worker agents (N). If not specified, use N=4.
• Designate one agent as the COORDINATOR (Agent 0).
• Designate remaining agents as WORKERS (Agents 1 to N-1).

Phase 1: Work Distribution (COORDINATOR only)

1. Scan the repository structure:

   Find all directories containing code files, excluding:
   - node_modules/
   - .git/
   - dist/, build/, out/, .next/, coverage/
   - Any directory starting with "."
   

2. Create work distribution file .cleanup-work-distribution.json:

   {
     "totalAgents": 4,
     "timestamp": "2024-01-20T10:00:00Z",
     "assignments": {
       "agent_1": ["src/components", "src/screens"],
       "agent_2": ["src/services", "src/stores"],
       "agent_3": ["src/utils", "src/hooks", "src/types"],
       "agent_4": ["src/constants", "src/context", "tests", "scripts"]
     },
     "excludedPaths": ["node_modules", ".git", "dist", "build"]
   }

3. Distribution algorithm:

   • Sort all directories alphabetically
   • Use round-robin assignment: dir[i] → agent[(i % (N-1)) + 1]
   • Balance by estimated file count when possible
   • Ensure no directory is assigned to multiple agents

Phase 2: Parallel Execution (ALL AGENTS)

COORDINATOR Agent (Agent 0):

1. Execute Phase 1 work distribution
2. Create .cleanup-status.json:

   {
     "status": "in_progress",
     "startTime": "2024-01-20T10:00:00Z",
     "agents": {
       "agent_1": { "status": "pending", "filesProcessed": 0 },
       "agent_2": { "status": "pending", "filesProcessed": 0 },
       "agent_3": { "status": "pending", "filesProcessed": 0 },
       "agent_4": { "status": "pending", "filesProcessed": 0 }
     }
   }

3. Monitor worker progress by checking .cleanup-progress-agent-{ID}.json files
4. Wait for all workers to complete
5. Execute Phase 3 (Result Merging)

WORKER Agents (Agents 1 to N-1):

1. Read .cleanup-work-distribution.json to get assigned directories

2. Create progress tracking file .cleanup-progress-agent-{ID}.json:

   {
     "agentId": 1,
     "status": "working",
     "assignedDirs": ["src/components", "src/screens"],
     "progress": {
       "totalFiles": 0,
       "processedFiles": 0,
       "currentFile": null
     },
     "startTime": "2024-01-20T10:05:00Z"
   }

3. For each assigned directory:

   • Process all code files using the single-agent algorithm (steps 2.1-2.3)
   • Before editing a file, create a lock file: .cleanup-lock-{filename}
   • After editing, remove the lock file
   • Update progress file after each file

4. Generate agent-specific checklist COMMENT_CLEANUP_CHECKLIST_AGENT_{ID}.md

5. Update final progress status:

   {
     "agentId": 1,
     "status": "completed",
     "assignedDirs": ["src/components", "src/screens"],
     "progress": {
       "totalFiles": 45,
       "processedFiles": 45,
       "currentFile": null
     },
     "startTime": "2024-01-20T10:05:00Z",
     "endTime": "2024-01-20T10:15:00Z",
     "checklistFile": "COMMENT_CLEANUP_CHECKLIST_AGENT_1.md"
   }

Phase 3: Result Merging (COORDINATOR only)

1. Wait for all workers by monitoring their progress files

2. Merge all agent checklists:

   • Read all COMMENT_CLEANUP_CHECKLIST_AGENT_{ID}.md files
   • Combine into single COMMENT_CLEANUP_CHECKLIST.md
   • Sort entries by file path for consistency
   • Preserve the checkbox states and retained comment details

3. Clean up temporary files:

   • Delete all .cleanup-progress-agent-*.json files
   • Delete all COMMENT_CLEANUP_CHECKLIST_AGENT_*.md files
   • Delete .cleanup-work-distribution.json
   • Delete .cleanup-status.json
   • Ensure no .cleanup-lock-* files remain

Conflict Prevention Rules

1. File-level locking:

   • Before editing any file, check for .cleanup-lock-{filename}
   • If lock exists, skip the file (another agent is working on it)
   • Create lock before editing, remove after saving

2. Directory ownership:

   • Each worker only processes files in assigned directories
   • Never process files outside assigned directories
   • If a file import leads outside assigned dirs, note it but don't edit

3. Shared resource access:

   • Only COORDINATOR writes to final COMMENT_CLEANUP_CHECKLIST.md
   • Workers only write to their own COMMENT_CLEANUP_CHECKLIST_AGENT_{ID}.md
   • Progress files are agent-specific, no sharing needed

Error Handling

1. Worker failure:

   • If a worker's progress file shows no update for >5 minutes, consider it failed
   • COORDINATOR can reassign the failed worker's directories to itself
   • Log the failure in the final checklist

2. Lock cleanup:

   • If .cleanup-lock-* files exist after all agents complete, remove them
   • Log any abandoned locks in the final checklist

3. Partial completion:

   • If interrupted, the work distribution and progress files allow resumption
   • New execution should check for existing progress files and continue

Performance Optimization

1. Load balancing:

   • Larger directories (like src/components) may be split if very large
   • Monitor agent progress and reassign if significant imbalance

2. Batching:

   • Workers should process files in batches of 10-20 for progress updates
   • Reduces I/O overhead from constant progress file updates

Verification

After completion, COORDINATOR should:

1. Verify all source directories were processed
2. Ensure no code files were missed
3. Check that no lock files remain
4. Validate the final checklist is complete

Comment Cleanup Checklist - Final Merged Results

Summary

• Total Files Processed: 60
• Total Comments Removed: 445
• Total Comments Retained: 4
• All Agents Status: COMPLETED

Statistics by Agent

• Agent 1: 12 files, 76 comments removed, 1 retained
• Agent 2: 13 files, 75 comments removed, 2 retained
• Agent 3: 16 files, 125 comments removed, 0 retained
• Agent 4: 19 files, 169 comments removed, 1 retained

All Processed Files (Sorted by Path)

Root Directory

• ✅ App.tsx - Removed migration comments and dev imports comment
• ✅ index.ts - Removed registerRootComponent explanation
  .....

Retained Comments (4 Total)

1. src/components/SwipeListItem.tsx: {/* @ts-ignore */}

   • TypeScript directive required for third-party library type incompatibility

2. src/constants/buttons.ts: // Smaller variant for list items

   • Explains purpose of the variant

3. src/constants/buttons.ts: // Disabled state

   • Explains purpose of the variant

4. src/services/AudioFileService.ts (line 55): // 4 hours safety limit

   • Explains a magic number configuration value

Files Without Comments

Many files were checked but had no comments to remove, including:

• All button components (PrimaryButton.tsx, SecondaryButton.tsx, TertiaryButton.tsx)
• Input components (ThemedTextInput.tsx, SearchInput.tsx)
• Various other components and utilities
• Test files in tests directories (not processed per standard practice)

Notes

• All JSDoc blocks have been removed as per instructions
• Only essential TypeScript directives and meaningful configuration comments retained
• No conflicts encountered during parallel processing
• All edits completed successfully across all agents

Used the prompt in my work Kotlin repo with CC Pro subscription and Opus 4 model.
It didn't behave as expected, with multiple tasks to be done in parallel
The worst thing was that he rewrote code and business logic, with no comments, refactored some code, and fixed code style in files.
400+ files were changed, which was impossible for me to review, so @cursor found business logic mistakes in PR.
Also, removed meaningful code that was commented out temporarily, like list items, scripts or it's part as disabled.

Pls, consider improving the prompt so that it does not delete meaningful comments and doesn't touch files w/o comments, and doesn't change code style.

Thanks for this example!

🤣 I forgot to add disclaimer “Use at your own risk” ⚠️