gh-thkt-claude-config/commands/review.md

---
description: >
  Orchestrate multiple specialized review agents with dynamic context analysis, hierarchical task decomposition, and confidence-based filtering.
  Use after code changes or when comprehensive quality assessment is needed. Includes security, performance, accessibility, type safety, and more.
  All findings include evidence (file:line) and confidence markers (✓/→/?) per Output Verifiability principles.
  複数の専門エージェントによるコードレビューを実行。セキュリティ、パフォーマンス、アクセシビリティなど包括的な品質評価。
allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git log:*), Bash(git show:*), Read, Glob, Grep, LS, Task
model: inherit
argument-hint: "[target files or scope]"
---

# /review - Advanced Code Review Orchestrator

## Purpose

Orchestrate multiple specialized review agents with dynamic context analysis, hierarchical task decomposition, and confidence-based filtering.

**Output Verifiability**: All review findings include evidence (file:line), distinguish verified issues (✓) from inferred problems (→), per AI Operation Principle #4.

## Integration with Skills

This command explicitly references the following Skills:

- [@~/.claude/skills/security-review/SKILL.md] - Security review knowledge based on OWASP Top 10

Other Skills are automatically loaded through each review agent's dependencies:

- `performance-reviewer` → `performance-optimization` skill
- `readability-reviewer` → `readability-review` skill
- `progressive-enhancer` → `progressive-enhancement` skill

## Dynamic Context Analysis

### Git Status

Check git status:

```bash
!`git status --porcelain`
```

### Files Changed

List changed files:

```bash
!`git diff --name-only HEAD`
```

### Recent Commits

View recent commits:

```bash
!`git log --oneline -10`
```

### Change Statistics

Show change statistics:

```bash
!`git diff --stat HEAD`
```

## Specification Context (Auto-Detection)

### Discover Latest Spec

Search for spec.md in SOW workspace using Glob tool (approved):

```markdown
Use Glob tool to find spec.md:
- Pattern: ".claude/workspace/sow/**/spec.md"
- Alternative: "~/.claude/workspace/sow/**/spec.md"

Select the most recent spec.md if multiple exist (check modification time).
```

### Load Specification

**If spec.md exists**, load it for review context:

- Provides functional requirements for alignment checking
- Enables "specification vs implementation" verification
- Implements Article 2's approach: spec.md in review prompts
- Allows reviewers to identify gaps like "仕様書ではこう定義されていますが、この実装ではそのケースが考慮されていません"

**If spec.md does not exist**:

- Review proceeds with code-only analysis
- Focus on code quality, security, and best practices
- Consider creating specification with `/think` for future reference

## Execution

Invoke the review-orchestrator agent to perform comprehensive code review:

```typescript
Task({
  subagent_type: "review-orchestrator",
  description: "Comprehensive code review",
  prompt: `
Execute comprehensive code review with the following requirements:

### Review Context
- Changed files: Use git status and git diff to identify scope
- Recent commits: Analyze recent changes for context
- Project type: Detect technology stack automatically
- Specification: If spec.md exists in workspace, verify implementation aligns with specification requirements
  - Check if all functional requirements (FR-xxx) are implemented
  - Identify missing features defined in spec
  - Flag deviations from API specifications
  - Compare actual vs expected behavior per spec

### Review Process
1. **Context Discovery**: Analyze repository structure and technology stack
2. **Parallel Reviews**: Launch specialized review agents concurrently
   - structure-reviewer, readability-reviewer, progressive-enhancer
   - type-safety-reviewer, design-pattern-reviewer, testability-reviewer
   - performance-reviewer, accessibility-reviewer
   - document-reviewer (if .md files present)
3. **Filtering & Consolidation**: Apply confidence filters and deduplication

### Output Requirements
- All findings MUST include evidence (file:line)
- Use confidence markers: ✓ (>0.8), → (0.5-0.8)
- Only include findings with confidence >0.7
- Group by severity: Critical, High, Medium, Low
- Provide actionable recommendations

Report results in Japanese.
  `
})
```

## Hierarchical Review Process Details

### Phase 1: Context Discovery

Analyze repository and determine review scope:

1. Analyze repository structure and technology stack
2. Identify review scope (changed files, directories)
3. Detect code patterns and existing quality standards
4. Determine applicable review categories

### Phase 2: Parallel Specialized Reviews

Launch multiple review agents concurrently:

- Each agent focuses on specific aspect
- Independent execution for efficiency
- Collect raw findings with confidence scores

### Phase 3: Filtering and Consolidation

Apply multi-level filtering with evidence requirements:

1. **Confidence Filter**: Only issues with >0.7 confidence
2. **Evidence Requirement**: All findings MUST include:
   - File path with line number (e.g., `src/auth.ts:42`)
   - Specific code reference or pattern
   - Reasoning for the issue
3. **False Positive Filter**: Apply exclusion rules
4. **Deduplication**: Merge similar findings
5. **Prioritization**: Sort by impact and severity

**Confidence Mapping**:

- ✓ High Confidence (>0.8): Verified issue with direct code evidence
- → Medium Confidence (0.5-0.8): Inferred problem with reasoning
- ? Low Confidence (<0.5): Not included in output (too uncertain)

## Review Agents and Their Focus

### Core Architecture Reviewers

- `review-orchestrator`: Coordinates all review activities
- `structure-reviewer`: Code organization, DRY violations, coupling
- `root-cause-reviewer`: Deep problem analysis, architectural debt

### Quality Assurance Reviewers

- `readability-reviewer`: Code clarity, naming, complexity
- `type-safety-reviewer`: TypeScript coverage, any usage, type assertions
- `testability-reviewer`: Test design, mocking, coverage gaps

### Specialized Domain Reviewers

- Security review (via `security-review` skill): OWASP Top 10 vulnerabilities, auth issues, data exposure
- `accessibility-reviewer`: WCAG compliance, keyboard navigation, ARIA
- `performance-reviewer`: Bottlenecks, bundle size, rendering issues
- `design-pattern-reviewer`: Pattern consistency, React best practices
- `progressive-enhancer`: CSS-first solutions, graceful degradation
- `document-reviewer`: README quality, API docs, inline comments

## Exclusion Rules

### Automatic Exclusions (False Positive Prevention)

1. **Style Issues**: Formatting, indentation (handled by linters)
2. **Minor Naming**: Unless severely misleading
3. **Test Files**: Focus on production code unless requested
4. **Generated Code**: Build outputs, vendor files
5. **Documentation**: Unless specifically reviewing docs
6. **Theoretical Issues**: Without concrete exploitation path
7. **Performance Micro-optimizations**: Unless measurable impact
8. **Missing Features**: vs actual bugs/issues

### Context-Aware Exclusions

- Framework-specific patterns (React/Angular/Vue idioms)
- Project conventions (detected from existing code)
- Language-specific safety (memory-safe languages)
- Environment assumptions (browser vs Node.js)

## Output Format with Confidence Scoring

**IMPORTANT**: Use both numeric scores (0.0-1.0) and visual markers (✓/→) for clarity.

```markdown
[REVIEW OUTPUT TEMPLATE]

Review Summary
- Files Reviewed: [Count and list]
- Total Issues: [Count by severity with markers]
- Review Coverage: [Percentage]
- Overall Confidence: [✓/→] [Average score]

## ✓ Critical Issues 🚨 (Confidence > 0.9)
Issue #1: [Title]
- **Marker**: [✓] High Confidence
- **File**: path/to/file.ts:42-45
- **Category**: security|performance|accessibility|etc
- **Confidence**: 0.95
- **Evidence**: [Specific code snippet or pattern found]
- **Description**: [Detailed explanation]
- **Impact**: [User/system impact]
- **Recommendation**: [Specific fix with code example]
- **References**: [Related files, docs, or standards]

## ✓ High Priority ⚠️ (Confidence > 0.8)
Issue #2: [Title]
- **Marker**: [✓] High Confidence
- **File**: path/to/another.ts:123
- **Evidence**: [Direct observation]
- **Description**: [Issue explanation]
- **Recommendation**: [Fix with example]

## → Medium Priority 💡 (Confidence 0.7-0.8)
Issue #3: [Title]
- **Marker**: [→] Medium Confidence
- **File**: path/to/file.ts:200
- **Inference**: [Reasoning behind this finding]
- **Description**: [Issue explanation]
- **Recommendation**: [Suggested improvement]
- **Note**: Verify this inference before implementing fix

Improvement Opportunities
[→] Lower confidence suggestions (0.5-0.7) for consideration
- Mark as [→] to indicate these are recommendations, not confirmed issues

Metrics
- Code Quality Score: [A-F rating] [✓/→]
- Technical Debt Estimate: [Hours] [✓/→]
- Test Coverage Gap: [Percentage] [✓]
- Security Posture: [Rating] [✓/→]

Recommended Actions
1. **Immediate** [✓]: [Critical fixes with evidence]
2. **Next Sprint** [✓/→]: [High priority items]
3. **Backlog** [→]: [Nice-to-have improvements]

Evidence Summary
- **Verified Issues** [✓]: [Count] - Direct code evidence
- **Inferred Problems** [→]: [Count] - Based on patterns/reasoning
- **Total Confidence**: [Overall score]
```

## Review Strategies

### Quick Review (2-3 min)

Focus areas:

- Security vulnerabilities
- Critical bugs
- Breaking changes
- Accessibility violations

Command: `/review --quick`

### Standard Review (5-7 min)

Includes Quick + :

- Performance issues
- Type safety problems
- Test coverage gaps
- Code organization

Command: `/review` (default)

### Deep Review (10+ min)

Comprehensive analysis:

- All standard checks
- Root cause analysis
- Technical debt assessment
- Refactoring opportunities
- Architecture evaluation

Command: `/review --deep`

### Focused Review

Target specific areas:

- `/review --security` - Security focus
- `/review --performance` - Performance focus
- `/review --accessibility` - A11y focus
- `/review --architecture` - Design patterns

## TodoWrite Integration

Automatic task creation:

```markdown
[TODO LIST TEMPLATE]
Code Review: [Target]
1. ⏳ Context discovery and scope analysis
2. ⏳ Execute specialized review agents (parallel)
3. ⏳ Filter and validate findings (confidence > 0.7)
4. ⏳ Consolidate and prioritize results
5. ⏳ Generate actionable recommendations
```

## Custom Review Instructions

Support for project-specific rules:

- `.claude/review-rules.md` - Project conventions
- `.claude/exclusions.md` - Custom exclusions
- `.claude/review-focus.md` - Priority areas

## Advanced Features

### Incremental Reviews

Compare against baseline:

```bash
!`git diff origin/main...HEAD --name-only`
```

### Pattern Detection

Identify recurring issues:

- Similar problems across files
- Systemic architectural issues
- Common anti-patterns

### Learning Mode

Track and improve:

- False positive patterns
- Project-specific idioms
- Team preferences

## Usage Examples

### Basic Review

```bash
/review
# Reviews all changed files with standard depth
```

### Targeted Review

```bash
/review "authentication module"
# Focuses on auth-related code
```

### Security Audit

```bash
/review --security --deep
# Comprehensive security analysis
```

### Pre-PR Review

```bash
/review --compare main
# Reviews changes against main branch
```

### Component Review

```bash
/review "src/components" --accessibility
# A11y review of components directory
```

## Best Practices

1. **Review Early**: Catch issues before they compound
2. **Review Incrementally**: Small, frequent reviews > large, rare ones
3. **Apply Output Verifiability**:
   - **Always provide evidence**: File paths with line numbers
   - **Use confidence markers**: ✓ for verified, → for inferred
   - **Explain reasoning**: Why is this an issue?
   - **Reference standards**: Link to docs, best practices, or past issues
   - **Never guess**: If uncertain, mark as [→] and explain the inference
4. **Act on High Confidence**: Focus on ✓ (>0.8) issues first
5. **Validate Inferences**: [→] markers require verification before fixing
6. **Track Patterns**: Identify recurring problems
7. **Customize Rules**: Add project-specific exclusions
8. **Iterate on Feedback**: Tune confidence thresholds

## Integration Points

### Pre-commit Hook

```bash
claude review --quick || exit 1
```

### CI/CD Pipeline

```yaml
- name: Code Review
  run: claude review --security --performance
```

### PR Comments

Results formatted for GitHub/GitLab comments

## Applied Development Principles

### Output Verifiability (AI Operation Principle #4)

All review findings MUST follow Output Verifiability:

- **Distinguish verified from inferred**: Use ✓/→ markers
- **Provide evidence**: File:line for every issue
- **State confidence explicitly**: Numeric + visual marker
- **Explain reasoning**: Why is this problematic?
- **Admit uncertainty**: [→] when inferred, never pretend to know

### Principles Guide

[@~/.claude/rules/PRINCIPLES_GUIDE.md](~/.claude/rules/PRINCIPLES_GUIDE.md) - Foundation for review prioritization

Application:

- **Priority Matrix**: Categorize issues by Essential > Default > Contextual principles
- **Conflict Resolution**: Decision criteria for DRY vs Readable, SOLID vs Simple, etc.
- **Red Flags**: Method chains > 3 levels, can't understand in 1 minute, "just in case" implementations

### Documentation Rules

[@~/.claude/docs/DOCUMENTATION_RULES.md](~/.claude/docs/DOCUMENTATION_RULES.md) - Review report format and structure

Application:

- **Clarity First**: Understandability over completeness
- **Consistency**: Unified report format with ✓/→ markers
- **Actionable Recommendations**: Specific improvement actions with evidence

## Next Steps After Review

- **Critical Issues** → `/hotfix` for production issues
- **Bugs** → `/fix` for development fixes
- **Refactoring** → `/think` → `/code` for improvements
- **Performance** → Targeted optimization with metrics
- **Tests** → `/test` with coverage goals
- **Documentation** → Update based on findings