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

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

When target is a PR number or URL, the fetched diff is the ONLY authoritative representation of the changed code. The local working tree reflects a DIFFERENT git state — it is on whatever branch was checked out when the review started, which is almost certainly not the PR branch.

Reading local files in PR mode produces silently wrong results:

• Changes introduced by the PR appear absent (local has the old code)
• Real bugs get declared "not present" → false REFUTED verdicts
• The review poisons findings with high confidence in wrong conclusions

Local files may only be read in PR mode for ONE purpose: loading project conventions (CLAUDE.md, linting config, sibling files for style context). Even then, only read files NOT in the PR's changed file set.

Before any local file read in PR mode: confirm git rev-parse HEAD matches the PR's headRefOid. If they differ, treat the local file as unavailable for that finding. </CRITICAL>

Phase Overview

Phase 1: Strategic Planning

Execute: /advanced-code-review-plan

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

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

Memory-Informed Planning: After resolving the review target, proactively load relevant memory:

• memory_recall(query="review finding [branch_or_module]") for prior findings on this area
• memory_recall(query="false positive [project]") for known false positive patterns

Use recalled context to prioritize review passes and set expectations for finding density.

Phase 2: Context Analysis

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.

Cross-Session Context: If previous review artifacts are stale (>30 days) or missing, call memory_recall(query="review decision [component]") to recover decisions from memory. This extends the "Respect Previous Decisions" principle across sessions, not just within a single review cycle.

Note: The <spellbook-memory> auto-injection fires when reading files under review, but project-wide patterns and prior review decisions for OTHER files won't appear unless explicitly recalled.

Phase 3: Deep Review

Multi-pass analysis: 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

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.

Persist Verified Findings: After verification, store findings with their verdicts:

memory_store_memories(memories='{"memories": [{"content": "[Finding]: [description]. Verdict: [CONFIRMED/REFUTED]. Evidence: [key evidence].", "memory_type": "[fact or antipattern]", "tags": ["review", "verified", "[category]"], "citations": [{"file_path": "[file]", "line_range": "[lines]"}]}]}')

• CONFIRMED findings: memory_type = "antipattern" (warns future reviews)
• REFUTED findings: memory_type = "fact" with tag "false-positive" (prevents re-flagging)

Phase 5: Report Generation

Execute: /advanced-code-review-report

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

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

Persist Review Summary: Store a high-level summary of the review outcome:

memory_store_memories(memories='{"memories": [{"content": "Review of [target]: [N] findings ([breakdown by severity]). Key themes: [themes]. Risk assessment: [level].", "memory_type": "fact", "tags": ["review-summary", "[target]", "[date]"], "citations": [{"file_path": "[report_path]"}]}]}')

This enables future reviews to reference historical review density and risk trends.

Constants and Configuration

Severity Order

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

Configurable Thresholds

Offline Mode

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>