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