Progressive Code Review Gate

When to Use

• Before every commit or push of code changes (mandatory, fires automatically)
• When user says "ready to commit," "push this," or "commit and push"
• NOT for: PR-level review (providing-code-review), language/profanity audit (professional-language-audit)

MANDATORY before every commit/push of code changes. Skip only when the human explicitly says to skip review.

Wrong skill? PR-level review of others' work → providing-code-review. File-protocol review → code-review.

Procedure

Step 1: Gather the diff

Determine what is being committed or pushed:

# For uncommitted changes (pre-commit):
git diff --staged                    # staged changes
git diff                             # unstaged changes

# For unpushed commits (pre-push):
git log --oneline @{u}..HEAD        # list unpushed commits
git diff @{u}..HEAD                 # diff of unpushed commits

If no diff exists in any of these, skip this gate.

Step 2: Check sentinel, then dispatch battery if needed

First, run the code-review-battery Phase 0 sentinel check:

SENTINEL="$(git rev-parse --show-toplevel 2>/dev/null || echo .)/.code-review-cleared"
cat "$SENTINEL" 2>/dev/null || echo "NO CLEARANCE"
echo "HEAD: $(git rev-parse HEAD 2>/dev/null)"
git diff --quiet && git diff --cached --quiet && echo "WORKTREE_CLEAN" || echo "WORKTREE_DIRTY"

If the sentinel is valid for HEAD AND WORKTREE_CLEAN: battery already ran on this code. Map the existing verdict to gate verdicts (see table below) and skip dispatch.

Otherwise: dispatch battery. Follow the code-review-battery skill procedure (Phase 1–5):

1. Phase 1 — Triage the diff → select relevant specialists (monolith only via --all or manual request)
2. Phase 2 — Diff + Source Context + Dispatch activated reviewers in parallel with diff + source context inline
3. Phase 3 — Aggregate findings, triple-filter, classify Implement/Defer/Reject
4. Phase 4 — Escalation if triggers fire (re-dispatch with diff + source context re-attached)
5. Phase 5 — Convergence check (stop/continue/escalate-to-human)

Map battery output to gate verdicts:

On FAIL re-review rounds (Round 2+): skip triage, re-dispatch the SAME reviewers from Round 1. On PASS_WITH_NITS re-review: use targeted Step 3a below (scoped files + scoped reviewers).

Fallback (only if parallel sub-agent dispatch is impossible — e.g., platform does not support firing multiple sub-agents simultaneously):

Invoke a single reviewer with the monolithic prompt below. Use whatever sub-agent mechanism is available (e.g., sub-agent-code-reviewer on Augment, Task() on Claude Code). Give it a unique name per round (e.g., review-round-1).

The monolithic reviewer MUST receive:

1. Repo path
2. Exact diff command matching the review scope
3. Instruction to read full source files
4. The monolithic checklist covering all review dimensions:

Review the code changes in {repo_path}.
Run `cd {repo_path} && {exact_diff_command}` to see the diff.
Read the full source files for all changed code.

Be harsh and adversarial. Check for:
1. Logic errors, off-by-one, edge cases
2. Missing error handling or silent failures
3. Inconsistency with surrounding code patterns
4. Security issues (injection, secrets, unsafe operations)
5. Stale references (functions/variables that no longer exist)
6. Missing downstream changes (callers, tests, types, docs)
7. Style violations relative to the project's conventions

Classify each issue:
- MUST-FIX: Blocks commit (logic error, security, correctness)
- SHOULD-FIX: Strong recommendation (inconsistency, missing guard)
- NIT: Minor (won't block)

Verdict: PASS, PASS_WITH_NITS, or FAIL
If FAIL: list every MUST-FIX and SHOULD-FIX clearly.

Step 3: Process results

Step 3a: Targeted re-review (PASS_WITH_NITS loop)

After fixing nits, run a targeted battery round:

1. Scope: Only the files touched by the nit fixes (not the full original diff)
2. Reviewers: Only the reviewer(s) that produced the nits in the previous round
3. Dispatch: Re-use the original diff command with -- <fixed-files> appended (see skills/engineering/code-review-battery/skill.md Phase 4 for scoping rules). Each reviewer instruction must include: reviewer prompt + diff + source context (per Phase 2 dispatch requirements).
4. Verdict mapping: Same table as Step 2
5. Exit conditions:
   • PASS → proceed to commit/push
   • PASS_WITH_NITS → fix and repeat Step 3a (counts toward Round 5 cap)
   • FAIL → fix and go to Step 2 (full re-review — nit fix introduced a real issue)

Why targeted, not full: Nit fixes are low-risk by definition. Re-reviewing the entire diff wastes time. But nit fixes can introduce new issues, so the affected reviewer must verify.

Step 4: Track rounds

• Round 1: Initial review (Step 2)
• Round 2+: Re-review after fixes (Step 2 for FAIL, Step 3a for PASS_WITH_NITS)
• Round 5: STOP. Tell the human: "5 review rounds without clean pass. Please review manually."

What This Gate Does NOT Do

• Does not run lint/typecheck/tests (that's pre-commit-gate, order 1)
• Does not enforce style guides (that's enforce-style-guide, order 2 — runs before this gate so style-induced code changes are covered by this review)
• Does not handle PR-level review (that's providing-code-review)
• Does not scan for unprofessional language (that's professional-language-audit, order 4)

Anti-Patterns

Failure Modes

Commit Gate Chain

Preferred: use-skill unified-commit-gate loads all 5 gates in one load. Use this skill directly only for deep-dive when the code review gate fails.

pre-commit-gate (1) → enforce-style-guide (2) → progressive-code-review-gate (3) → professional-language-audit (4) → public-repo-ip-audit (5)

Companion Skills

• code-review-battery: The review engine this gate dispatches
• pre-commit-gate: Runs before this gate (lint/tests)
• enforce-style-guide: Runs before this gate (style fixes)
• providing-code-review: Engineering rigor checklist (informs review focus)
• progressive-harsh-review: Progressive review enforcement
• feature-development: Full feature workflow (uses this gate)
• micro-harsh-review: Per-batch review (lighter)