pre-commit-review

What this skill does

<objective>
Expert design analysis that detects issues linters can't catch.
Returns detailed report to caller with categorized findings and fix recommendations.

**Pure Analysis & Reporting** - Generates report, doesn't fix anything or invoke skills.

**Reference**: See `reference.md` for complete detection checklist with examples.
**Examples**: See `examples.md` for real-world review scenarios.
</objective>

<quick_start>
1. **Read files** under review (all staged or specific files)
2. **Check package sizes** — normally surfaced automatically by the plugin's PostToolUse hook (`hooks/check-package-sizes.sh`). For review-only sessions (no recent edits), count non-test `.go` files per touched directory: red (≥13) → Design Debt; yellow (8–12) → Polish.
3. **Apply design principles** checklist from reference.md (LLM reasoning)
4. **Search usage patterns** with Grep tool
5. **Categorize findings**: Bugs, Design Debt, Readability Debt, Polish
6. **Generate structured report** with file:line locations and fix recommendations
7. **Return report** to caller (no fixes, no skill invocations)
</quick_start>

<input_output>
<input>
- Files to review (specific files or all staged changes)
- Review mode: `full` (first run) or `incremental` (subsequent runs)
- Previous findings (optional, for incremental mode)
- Context (invoked by refactoring, orchestrator, subagent, or user)
</input>

<output>
- Structured report with categorized findings
- Each finding: `file:line`, issue, why it matters, fix strategy, effort estimate
- Prioritized by impact and effort
- Format: Parseable for combined analysis (when invoked by orchestrator)
</output>
</input_output>

<invocation_modes>
<direct_skill_invocation context="User or Orchestrator">
- Full control, can invoke other skills
- Can make changes based on findings
- Interactive mode with user feedback
</direct_skill_invocation>

<subagent_mode context="Task tool with go-code-reviewer">
- Read-only analysis, returns report only
- Cannot invoke other skills
- Used for parallel execution by orchestrator
- Designed for speed and focused analysis
</subagent_mode>
</invocation_modes>

<who_invokes>
1. **go-code-reviewer agent** - Loads this skill for design analysis guidance during parallel quality analysis
2. **@refactoring skill** - After applying patterns, validates design quality remains high
3. **User** - Manual code review before commit
</who_invokes>

<detection_capabilities>
**What Reviewer Detects (That Linters Can't):**
- Primitive obsession (with juiciness scoring)
- Unstorified functions (mixed abstraction levels)
- Missing domain concepts (implicit types that should be explicit)
- Non-self-validating types (defensive code in methods, reliance on upstream validation, re-validation of composed types)
- Poor comment quality (explaining what instead of why)
- File structure issues (too long, too many types)
- Package size zone violations: surfaced automatically by the plugin's PostToolUse hook after edits. Thresholds: ≥13 non-test `.go` files at one directory level = red (Design Debt, hard gate); 8–12 = yellow (Polish, review before adding the next file). For review-only sessions where no edit has fired the hook, verify manually before reporting. When a violation is reported, apply the 3-step design review: (1) does the package name reflect a real-world domain concept — not a role or container? (2) are there big structs with disjoint method sets or primitive-obsession fields hiding new types? (3) only after that review, decide whether to extract sub-packages, new leaf types, or both.
- Generic package extraction opportunities
- Design bugs (nil deref, ignored errors, resource leaks)
- Test quality (weak assertions, missing use cases, mock overuse, conditionals in tests)

**Division of Labor:**
- **Linter handles**: Complexity metrics, line counts, formatting, syntax
- **Reviewer handles**: Design patterns, domain modeling, conceptual issues

See [reference.md](./reference.md) for complete detection checklist with examples.
</detection_capabilities>

<workflow>

<full_review_mode context="First Run">
1. Read all files under review (using Read tool)
2. Check package sizes: the plugin's PostToolUse hook surfaces yellow/red zones automatically after edits; for review-only sessions, count non-test `.go` files per touched directory. Red (≥13) → Design Debt finding. Yellow (8–12) → Polish finding.
3. Apply design principles checklist from reference.md (LLM reasoning)
4. Search for usage patterns across codebase (using Grep tool)
5. Categorize findings:
   - Bugs (nil deref, ignored errors, resource leaks)
   - Design Debt (types, architecture, validation)
   - Readability Debt (abstraction, flow, clarity)
   - Polish (naming, docs, minor improvements)
6. Generate structured report with recommendations
7. Return report to caller (doesn't invoke other skills or make fixes)
</full_review_mode>

<incremental_review_mode context="Subsequent Runs">
Used after fixes have been applied to verify resolution and detect new issues.

1. Read ONLY changed files since last review (using git diff)
2. Compare against previous findings:
   - Mark resolved issues as Fixed
   - Identify issues that still exist
3. Analyze changed code for NEW issues introduced by fixes
4. Generate delta report:
   - Fixed: Issues from previous run that are now resolved
   - Remaining: Issues that still need attention
   - New: Issues introduced by recent changes
5. Return concise delta report (not full analysis)

**When to Use Incremental Mode:**
- After @refactoring skill applies fixes
- During iterative fix loop in Phase 4 of autopilot workflow
- User requests re-review after making changes

**Benefits:**
- Faster execution (only analyzes changed files)
- Clear feedback on what was fixed vs what remains
- Detects regressions introduced by fixes
</incremental_review_mode>

</workflow>

<detection_approach>
**LLM-Powered Analysis** (not AST parsing or metrics calculation):

The reviewer reads code like a senior developer and applies design principles:
- Reads files with Read tool
- Searches patterns with Grep tool (find usages, duplications)
- Applies checklist from reference.md using LLM reasoning
- Pattern matches against anti-patterns
- Counts occurrences and calculates juiciness scores
- Generates findings with specific locations and fix guidance
</detection_approach>

<report_format>

<full_report context="First Run">
```
📊 CODE REVIEW REPORT
Scope: [files reviewed]
Mode: FULL

SUMMARY

Total findings: 18
🐛 Bugs: 2 (fix immediately)
🔴 Design Debt: 5 (fix before commit)
🟡 Readability Debt: 8 (improves maintainability)
🟢 Polish: 3 (nice to have)

Estimated fix effort: 3.5 hours

[Detailed findings by category]
[Recommendations by priority]
[Skills to use for fixes]
```
</full_report>

<incremental_report context="Subsequent Runs">
```
📊 CODE REVIEW DELTA REPORT
Scope: [changed files only]
Mode: INCREMENTAL

SUMMARY

✅ Fixed: 4 (resolved from previous run)
⚠️ Remaining: 2 (still need attention)
🆕 New: 1 (introduced by recent changes)

[Detailed delta findings]
```
</incremental_report>

<structured_output context="For Orchestrator Parsing">
When invoked as subagent for combined analysis, output follows strict format:

```
🐛 BUGS
────────────────────────────────────────────────
file:line | Issue description | Why it matters | Fix strategy | Effort: [Trivial/Moderate/Significant]

🔴 DESIGN DEBT
────────────────────────────────────────────────
file:line | Issue description | Why it matters | Fix strategy | Effort: [Trivial/Moderate/Significant]

🟡 READABILITY DEBT
────────────────────────────────────────────────
file:line | Issue description | Why it matters | Fix strategy | Effort: [Trivial/Moderate/Significant]

🟢 POLISH
────────────────────────────────────────────────
file:line | Issue description | Why it matters | Fix strategy | Effort: [Trivial/Moderate/Significant]
```

**Effort Estimates:**
- **Trivial**: <5 minutes (extract constant, rename varia