ImaginerLabs/pre-commit-review

Pre-Commit Review — Intelligent Commit Quality Gates

Overview

Pre-commit-review is a chain-combined behavioral specification skill that merges:

• git-commit — Intelligent commit behavior规范
• code-review — Review judgment and criteria
• staged-code-review — Focused pre-commit workflow

The core judgment it encapsulates: "When should I require review before committing, and what should that review cover?"

This skill doesn't just execute a workflow — it embodies the decision-making framework of an experienced developer who knows when commits need extra scrutiny.

Core Philosophy

The Commit Readiness Spectrum

Not every commit needs review. This skill helps you navigate the spectrum:

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Quick Fix  │ ──► │  Normal Push  │ ──► │  Major UX   │
│  (instant)  │     │  (reviewed)  │     │  (reviewed) │
└─────────────┘     └──────────────┘     └─────────────┘
     │                    │                    │
     │                    │                    │
     ▼                    ▼                    ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│ Any pattern │     │   Complex    │     │  Breaking   │
│ Trivial fix │     │   logic      │     │  changes    │
│ Doc updates │     │   Business   │     │  New API    │
└─────────────┘     │   logic      │     └─────────────┘
                    └──────────────┘

The Pre-Commit Decision Tree

                    ┌─ Is this a hotfix?
                    │   └─ NO → Continue
                    │       └─ YES → Commit freely (but document)
                    │
                    └─ Does this affect other teams?
                        └─ YES → Require review
                        └─ NO → Continue
                                │
                                └─ Is logic complex (>10 lines changed)?
                                    └─ YES → Recommend review
                                    └─ NO → Continue
                                            │
                                            └─ Does this touch security/auth?
                                                └─ YES → Require review
                                                └─ NO → Commit freely

Behavioral Specification

Phase 1: Pre-Commit Self-Review

Before EVERY commit, run through these checkpoints:

1.1 Staged Changes Analysis

# Review what you're about to commit
git diff --staged --stat

# Check for unexpected changes
git diff --staged --name-only

Ask yourself:

• Are all these changes intentional?
• Are there any debug statements or console.logs?
• Are there any .env or credentials files staged?

1.2 Code Quality Gates

Run these checks mentally (or with tools):

| Check | What to Look For | |-------|------------------| | Naming | Variables/functions clearly named? | | Complexity | Any function >20 lines doing multiple things? | | Comments | Comments explain WHY, not WHAT? | | Tests | Logic changes have corresponding tests? | | Types | New code properly typed (TypeScript)? |

1.3 Commit Message Check

Does your commit message follow convention?

<type>(<scope>): <subject>

[optional body]

[optional footer]

Check:

• Subject line ≤72 characters
• Uses imperative mood ("add" not "added")
• Describes WHAT changed, not HOW
• Body explains WHY if non-obvious

Phase 2: Risk Assessment

Determine if this commit needs extra review:

High-Risk Commits (Require Review)

| Risk Type | Indicators | Action | |-----------|------------|--------| | Security | Auth, permissions, data handling | Mandatory review | | Data | Database, migrations, queries | Mandatory review | | API | Endpoint changes, contracts | Mandatory review | | Breaking | Public API, major behavior | Mandatory review |

Medium-Risk Commits (Review Recommended)

| Risk Type | Indicators | Action | |-----------|------------|--------| | Business | Core logic, calculations | Consider review | | Complex | Multi-file, non-trivial | Consider review | | Shared | Utils, shared components | Consider review |

Low-Risk Commits (Self-Approve)

| Type | Examples | |------|----------| | Chores | Deps, configs, build | | Docs | Readme, comments | | Fixes | Simple bug fixes (1-3 lines) | | Refactors | Rename, format (no logic) |

Phase 3: Quick Review Protocol

When review IS needed, here's the focused protocol:

What to Review (5 minutes max)

1. Correctness: Does the code do what it claims?
2. Safety: Any security or data integrity risks?
3. Clarity: Can someone understand this in 6 months?
4. Tests: Are there tests for the new logic?

What NOT to Review (Save for later)

• Style debates (use linters)
• Minor nits (non-blocking)
• "I would have done it differently" (opinion)
• Future concerns (out of scope)

Commit Type Recommendations

Based on risk assessment, here's when to use each type:

| Type | When to Use | Review Needed? | |------|-------------|----------------| | feat | New features | Recommended | | fix | Bug fixes | Low risk: No / High risk: Yes | | docs | Documentation | No | | refactor | Restructure (no behavior change) | Low risk: No / Complex: Yes | | perf | Performance improvements | Recommended | | test | Adding tests | No | | build | Build system changes | Yes | | ci | CI/CD changes | Yes | | chore | Maintenance | No |

The Pre-Commit Review Checklist

PRE-COMMIT REVIEW CHECKLIST
==========================

□ 1. Changes are intentional
□ 2. No debug code (console.log, debugger)
□ 3. No credentials or secrets
□ 4. Code follows project conventions
□ 5. Types are properly defined
□ 6. Tests cover new logic
□ 7. Commit message follows convention
□ 8. Subject line ≤72 chars
□ 9. Imperative mood used
□ 10. Breaking changes documented

RISK ASSESSMENT
===============
□ Security-sensitive changes?
□ Data integrity affected?
□ API contract changed?
□ Breaking change?

REVIEW REQUIRED? [ ] YES  [ ] NO
If YES, reviewer: _______________

Integration with git-commit

When using git-commit, extend it with pre-commit-review judgment:

Commit Flow

1. git add <files>
2. Run pre-commit-review judgment
3. Based on risk assessment:
   - Low risk → Proceed with git commit
   - Medium risk → Do quick self-review
   - High risk → Find a reviewer first
4. Write commit message (use convention)
5. Execute commit

Commit Message Template

<type>(<scope>): <subject>

<body>

<footer>
---
Reviewed by: [reviewer]
Risk level: [low/medium/high]
Tests added: [yes/no]
Breaking change: [yes/no]

Common Scenarios

Scenario 1: "Is this commit ready?"

Analysis:
- 3 files changed, 50 lines added
- Touches authentication logic
- Adds new API endpoint

Risk: HIGH (security + API)

Recommendation: Get review before committing.

Scenario 2: "Quick documentation fix"

Analysis:
- 1 file changed, 5 lines
- Documentation only
- No logic affected

Risk: LOW

Recommendation: Commit freely.

Scenario 3: "Refactoring a shared utility"

Analysis:
- 5 files changed
- Shared utility used by 10+ places
- No behavior change (rename/format)

Risk: MEDIUM (high blast radius)

Recommendation: Self-review carefully, or get quick review from one person.

Key Principles

1. Review is a Gift

Code review isn't criticism — it's collaboration. Frame it positively.

2. Small Commits = Easy Reviews

Large commits are hard to review. If you need review, small commits are easier to approve.

3. Trust, but Verify

Your judgment about "is this ready" improves with experience. This skill helps you formalize that judgment.

4. Context Matters

The same change might need review in one codebase but not another. Consider:

• Team size
• Code ownership
• Release cadence
• Risk tolerance

5. When in Doubt, Review

If you're unsure whether to review, the answer is usually "yes."

Relationship to Other Skills

• git-commit — The commit execution skill this builds upon
• code-review — Provides the review criteria
• staged-code-review — Provides the focused review protocol
• safe-refactor — Use before refactoring to ensure coverage
• test-think — Use to determine what tests are needed