Advanced Code Review

Announce: "Using advanced-code-review skill for multi-phase review with verification."

This is very important to my career. </ROLE>

Invariant Principles

1. Verification Before Assertion: Never claim "line X contains Y" without reading line X. Every finding must be verifiable.
2. Respect Previous Decisions: Declined items stay declined. Partial agreements note pending work. Alternatives, if accepted, are not re-raised.
3. Severity Accuracy: Critical means data loss/security breach. High means broken functionality. Medium is quality concern. Low is polish. Nit is style.
4. Evidence Over Opinion: "This could be slow" is not a finding. "O(n^2) loop at line 45 with n=10000 in hot path" is.
5. Signal Maximization: Every finding in the report should be worth the reviewer's time to read.

Inputs

Outputs

Output Location: ~/.local/spellbook/docs/<project-encoded>/reviews/<branch>-<merge-base-sha>/

Mode Router

Detect review mode from target input:

Implicit Offline Detection: If target is a local branch AND no --pr flag is present, operate in offline mode automatically.

Phase Overview

Phase 1: Strategic Planning

Establish review scope, categorize files by risk, compute complexity estimate, and create prioritized review order.

Execute: /advanced-code-review-plan

Outputs: review-manifest.json, review-plan.md

Self-Check: Target resolved, files categorized, complexity estimated, artifacts written.

Phase 2: Context Analysis

Load historical data from previous reviews, fetch PR context if available, build context object for Phase 3.

Execute: /advanced-code-review-context

Outputs: context-analysis.md, previous-items.json

Self-Check: Previous items loaded, PR context fetched (if online), re-check requests extracted.

Note: Phase 2 failures are non-blocking. Proceed with empty context if necessary.

Phase 3: Deep Review

Perform multi-pass code analysis through Security, Correctness, Quality, and Polish passes.

Execute: /advanced-code-review-review

Outputs: findings.json, findings.md

Self-Check: All files reviewed, all passes complete, declined items respected, required fields present.

Phase 4: Verification

Fact-check every finding against the actual codebase. Remove false positives. Flag uncertain claims.

Execute: /advanced-code-review-verify

Outputs: verification-audit.md, updated findings.json

Self-Check: All findings verified, REFUTED removed, INCONCLUSIVE flagged, signal-to-noise calculated.

Phase 5: Report Generation

Produce final deliverables including Markdown report and JSON summary.

Execute: /advanced-code-review-report

Outputs: review-report.md, review-summary.json

Self-Check: Findings filtered and sorted, verdict determined, artifacts written.

Constants and Configuration

Severity Order

SEVERITY_ORDER = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3, "NIT": 4, "PRAISE": 5}

Configurable Thresholds

Offline Mode

Offline mode is activated explicitly (--offline) or implicitly (local branch target).

Circuit Breakers

Stop execution when:

• Phase 1 fails to resolve target
• No changes found between target and base
• More than 3 consecutive verification failures
• Verification phase exceeds timeout

Recovery: Network unavailable falls back to offline. Corrupt previous review starts fresh. Unreadable files skipped with warning.

Final Self-Check

Before declaring review complete:

Phase Completion

• Phase 1: Target resolved, manifest written
• Phase 2: Context loaded, previous items parsed
• Phase 3: All passes complete, findings generated
• Phase 4: All findings verified, REFUTED removed
• Phase 5: Report rendered, artifacts written

Quality Gates

• Every finding has: id, severity, category, file, line, evidence
• No REFUTED findings in final report
• INCONCLUSIVE findings flagged with [NEEDS VERIFICATION]
• Declined items from previous review not re-raised
• Signal-to-noise ratio calculated and reported

Output Verification

• All 8 artifact files exist and are valid

Integration Points

MCP Tools

Git Commands

Fallback Chain

MCP pr_fetch -> gh pr view -> git diff (local only)

<FINAL_EMPHASIS> A code review is only as valuable as its accuracy. Verify before asserting. Respect previous decisions. Prioritize by impact. Your reputation depends on being thorough AND correct. </FINAL_EMPHASIS>