reviewing-comments

---

name: reviewing-comments description: "Comment quality review. Detects LLM generation traces, implementation history, conversational tone, HOW vs WHY patterns, and redundant comments." allowed-tools: Read, Grep, Glob

Review criteria

Principle: Comments should serve their intended purpose - providing context and intent, not restating code or revealing generation artifacts.

LLM generation traces

• AI/LLM/Claude mentions in comments or code
• "Generated by", "Created by" markers
• Must be removed for production readiness

Implementation history in comments

• "Added for X", "To fix Y" (belongs in commit message, not code)
• 「〇〇のために追加」「△△に対応」
• Historical context should be in version control, not comments

Conversational tone

• "Here we", "This allows", "Let's", "Now we"
• 「ここでは」「これにより」「次に」
• Comments should be declarative, not conversational

HOW vs WHY violation

• Comments explaining implementation details (HOW): technology names, algorithm steps, data structure details
• Comments must explain intent (WHY): business purpose, domain terms, constraints
• Example: "Uses SHA-256 to hash passwords" (HOW) → "Passwords must be hashed for security compliance" (WHY)

Redundant comments

• Comments that duplicate what code already expresses clearly
• Example: // Set name to user name above this.name = user.name
• Self-documenting code is preferred

Missing documentation

• Public API without Purpose, Parameters, Return documentation
• Complex domain logic without WHY explanation

Review workflow

Copy this checklist and track your progress:

CopyProgress:
- [ ] Step 1: Parse GATHERED_INFO, TICKET_PATH, and CONFIG
- [ ] Step 2: Load project knowledge
- [ ] Step 3: Check criteria and detect violations
- [ ] Step 4: Score each finding (0-100)
- [ ] Step 5: Generate report

Step 1: Parse GATHERED_INFO, TICKET_PATH, and CONFIG

Parse from task prompt:

• GATHERED_INFO: code changes to review
• TICKET_PATH: target ticket folder path
• CONFIG: project configuration

Step 2: Load project knowledge

Run: python ~/.claude/scripts/resolve_knowledge.py --refs "${TICKET_PATH}/knowledge-refs.md" --workflow "/code-review" --base "${CONFIG.BASE_PATH}"

• On success/partial: use knowledge[].content for Terminology section and project-specific comment conventions
• On failure: continue without knowledge (use general best practices)

Step 3: Check criteria and detect violations

Check each criterion in Review criteria section against GATHERED_INFO and detect violations.

Step 4: Score each finding (0-100)

For each finding, assign confidence score based on evidence strength:

• 100: Absolutely certain, definitely real
• 75: Highly confident, real and important
• 50: Moderately confident, real but minor
• 25: Somewhat confident, might be real
• 0: Not confident, false positive

Step 5: Generate report

Output format:

Copy## Comments Review

Found X issues:

1. [Score: 95] Description

   file:line

2. [Score: 82] Description

   file:line