review-comments

Review Comments Skill

Review and improve code comments in staged files before committing: add missing doc comments, remove noise, and add LLM-friendly context.

Quick Reference

Trigger: review-comments or "review comments in staged files"

Scope: Only staged files (git diff --cached --name-only)

What to Fix

Add doc comments for

• Exported functions, classes, methods, and interface methods
• Comments describe WHAT, not HOW
• 1–3 lines for most cases

Inline comments — Add for

• Complex or non-obvious business logic
• // TODO: for incomplete implementations
• // NOTE: for important context
• Domain-specific rules (e.g., // GAD-7 is a 7-item questionnaire)
• Non-obvious constraints (e.g., // Auth tokens expire after 1 hour)
• Algorithm intent (e.g., // Process in batches of 1000 for performance)
• Edge cases (e.g., // Treat as active only when deleted_at is null)

Remove

• Obvious comments that repeat the code
• Stale comments no longer matching the code
• Commented-out code (unless explicitly kept for a reason)

Style Rules

• Write comments in English (LLM understanding + international collaboration)
• Avoid redundant headers (// Constructor, // Import statements)
• Interface methods: every method must have a doc comment

Steps

1. git diff --cached --name-only — get staged file list
2. For each file: read → analyze → apply guidelines
3. Edit files to add/update/remove comments
4. Report changes made

Output Format

Files reviewed: N
Comments added: N (describe what was added)
Comments updated: N (describe what was updated)
Comments removed: N (describe what was removed)

Related Skills

• pr-reviewer-3a — Full PR review including logic
• quality-gate — Gate 2 uses this skill