---
name: code-review
description: Run multi-lens code review on target files. Analyzes for bloat, smells, dead-code, redundancy, security, error-handling, coupling, boundaries, and evolvability. Interactive - asks before filing issues.
---

# Code Review Skill

Run focused code analysis using multiple review lenses. Findings are synthesized and presented for your approval before any issues are filed.

## When to Use

Invoke this skill when:
- "Review this code"
- "Run code review on src/"
- "Check this file for issues"
- "Analyze the codebase"
- `/code-review`

**Tip:** For best results, run `verify-work` first to ensure the code builds, and `test-review` to audit test quality. `code-review` focuses on static quality, not correctness.

## Arguments

The skill accepts an optional target:
- `/code-review` - Reviews recently changed files (git diff)
- `/code-review src/` - Reviews specific directory
- `/code-review src/main.py` - Reviews specific file
- `/code-review --diff HEAD~5` - Reviews changes in last 5 commits

## Available Lenses

Lenses are focused review prompts located in `~/.config/lenses/code/` or `skills/code-review/lenses/`:

| Lens | Focus |
|------|-------|
| `bloat.md` | File size, function length, complexity, SRP violations |
| `smells.md` | Code smells, naming, control flow, readability |
| `dead-code.md` | Unused exports, zombie code, unreachable paths |
| `redundancy.md` | Duplication, parallel systems, YAGNI violations |
| `security.md` | Injection, auth gaps, secrets, crypto misuse |
| `defense-in-depth.md` | **NEW:** Structural impossibility of bugs (4-layer validation) |
| `properties.md` | **NEW:** Opportunities for Property-Based Testing |
| `error-handling.md` | Swallowed errors, missing handling, failure modes |
| `coupling.md` | Tight coupling, circular deps, layer violations |
| `boundaries.md` | Layer violations, dependency direction, domain cohesion |
| `evolvability.md` | Hard-coded policies, missing seams, change amplification |

## Workflow

### Phase 1: Target Selection
1. Parse the target argument (default: git diff of uncommitted changes)
2. Identify files to review
3. Show file list to user for confirmation

### Phase 2: Lens Execution
For each lens, analyze the target files:

1. Read the lens prompt from `~/.config/lenses/code/{lens}.md`
2. Apply the lens to the target code
3. Collect findings in structured format

**Finding Format:**
```
[TAG] <severity:HIGH|MED|LOW> <file:line>
Issue: <one-line description>
Suggest: <actionable fix>
Evidence: <why this matters>
```

### Phase 3: Synthesis
After all lenses complete:
1. Deduplicate overlapping findings
2. Group related issues
3. Rank by severity and confidence
4. Generate summary report

**Optional:** If user requests consensus (`--orch` or asks for it):
```bash
orch consensus "<findings summary>" gpt gemini
```
Use this to filter false positives and prioritize.

### Phase 4: Interactive Review
Present findings to user:
1. Show executive summary (counts by severity)
2. List top issues with details
3. Ask: "Which findings should I file as issues?"

**User can respond:**
- "File all" - creates beads issues for everything
- "File HIGH only" - filters by severity
- "File 1, 3, 5" - specific findings
- "None" - just keep the report
- "Let me review first" - show full details

### Phase 5: Issue Filing (if requested)
For approved findings:
1. Create beads issues with `bd create`
2. Include lens tag, severity, file location
3. Link related issues if applicable

## Output

The skill produces:
1. **Console summary** - immediate feedback
2. **Beads issues** - if user approves filing

## Example Session

```
User: /code-review src/cli.py

Agent: I'll review src/cli.py with 9 lenses.

[Running bloat lens...]
[Running smells lens...]
[Running dead-code lens...]
[Running redundancy lens...]
[Running security lens...]
[Running error-handling lens...]
[Running coupling lens...]
[Running boundaries lens...]
[Running evolvability lens...]

## Review Summary: src/cli.py

| Severity | Count |
|----------|-------|
| HIGH     | 1     |
| MED      | 3     |
| LOW      | 2     |

### Top Issues

1. [BLOAT] HIGH src/cli.py:145-280
   Issue: Function `handle_request` is 135 lines
   Suggest: Extract into smaller functions by responsibility

2. [SMELL] MED src/cli.py:89
   Issue: Magic number 3600 without explanation
   Suggest: Extract to named constant SECONDS_PER_HOUR

3. [DEAD] MED src/cli.py:12
   Issue: Import `unused_module` has no references
   Suggest: Remove unused import

Would you like me to file any of these as beads issues?
Options: all, HIGH only, specific numbers (1,2,3), or none
```

## Configuration

The skill respects `.code-review.yml` in the repo root if present:

```yaml
# Optional configuration
ignore_paths:
  - vendor/
  - node_modules/
  - "*.generated.*"

severity_defaults:
  bloat: MED
  dead-code: LOW

max_file_size_kb: 500  # Skip files larger than this
```

## Guidelines

1. **Be Thorough But Focused** - Each lens checks one concern deeply
2. **Evidence Over Opinion** - Cite specific lines and patterns
3. **Actionable Suggestions** - Every finding needs a clear fix
4. **Respect User Time** - Summarize first, details on request
5. **No Spam** - Don't file issues without explicit approval

## Process Checklist

1. [ ] Parse target (files/directory/diff)
2. [ ] Confirm scope with user if large (>10 files)
3. [ ] Run each lens, collecting findings
4. [ ] Deduplicate and rank findings
5. [ ] Present summary to user
6. [ ] Ask which findings to file
7. [ ] Create beads issues for approved findings
8. [ ] Report issue IDs created

## Integration

- **Lenses**: Read from `~/.config/lenses/code/*.md`
- **Issue Tracking**: Uses `bd create` for beads issues
- **Orch**: Optional consensus filtering via `orch consensus`
