jacobjmc/priority-review

Priority Code Review

Review code changes for real, actionable defects. Prioritize precision over exhaustive exploration. Report only issues with a plausible failure path tied to the change.

Scope

• Review diffs, PRs, or commits and the code paths they affect.
• Focus on security, correctness, reliability, data integrity, and breaking regressions.
• Reference unchanged code only when needed to explain a failure introduced by the change.
• Do not report style preferences, feature ideas, or speculative concerns without concrete impact.

Severity and Confidence

Severity (P0-P3)

P0 - Critical (must fix)

• Security vulnerabilities (hardcoded secrets, injection, auth bypass)
• Data corruption or irreversible loss
• Crashes/outages in reachable paths
• Severe breaking changes that make core flows fail

P1 - High (should fix before merge)

• User-visible correctness bugs in common paths
• Missing/incorrect error handling causing request/job failure
• Concurrency/state bugs with realistic reachability
• Incomplete migrations or contract changes likely to break consumers

P2 - Medium

• Edge-case correctness bugs with clear impact
• Type or validation gaps likely to fail at runtime
• Performance regressions with concrete user or system impact

P3 - Low

• Low-severity correctness or maintainability risk introduced by the change
• Limited-impact fallback/default handling mistakes
• Latent bug risk with narrow reachability and clear evidence

Confidence

• high: Direct code evidence and clear failure path from the change
• medium: Strong evidence with one reasonable assumption
• low: Plausible concern that needs validation; report under Needs verification, not as a blocker

Review Workflow

Pass 1: Gather Minimal Context and Triage

• Collect the smallest sufficient git context for the review mode.
• Start with changed files and diff; read surrounding code only when needed.
• Identify risk signals and form defect hypotheses before deep investigation.

Examples (choose only what is needed):

• Uncommitted: git status --porcelain, git diff, git diff --cached
• PR/branch: git log --oneline {base}..HEAD, git diff {base}...HEAD --stat, git diff {base}...HEAD
• Commit: git show {sha} --stat, git diff {sha}^..{sha}

Risk Signals (trigger deeper review)

• Auth, permissions, session, secrets, crypto
• Input parsing, validation, serialization, SQL, file/path handling
• Async/concurrency, shared state, retries, idempotency, caching
• Data models, migrations, backfills, schema or contract changes
• Money, billing, quotas, usage accounting
• Error handling, timeouts, fallbacks, feature flags

Pass 2: Targeted Investigation (Bounded)

• Investigate only when a plausible defect hypothesis exists.
• Prioritize highest-risk hypotheses first.
• Read local context, related callers/callees, and affected invariants.
• Use sub-agents only for complex targeted checks; cap to 2-3 parallel probes.
• Do not spawn broad exploratory investigations for every category.

Optional Custom Rules

If .priority-review-rules.json exists in the repository root, load it and check changed files for rule matches.

Minimal rule format:

{
  "rules": [
    {
      "id": "no-console-log",
      "title": "No console.log in production code",
      "severity": "P2",
      "pattern": "console\\.log"
    }
  ]
}

• Report rule violations at the rule severity.
• Check changed files by default unless the rule explicitly requires broader scope.

Findings: Evidence Standard

Report only issues with a plausible execution or failure path caused by the change.

For each finding, include:

• Severity (P0-P3) and confidence (high or medium)
• Changed-file anchor (file:line) when possible
• Concrete impact (what fails, breaks, leaks, or corrupts)
• Causal explanation (why the change creates the issue)

If confidence is low, place it under Needs verification instead of P0/P1/P2/P3.

Report Format

Report findings by priority (P0 -> P3).

For each finding:

**[P{0-3}][{high|medium}] {file}:{line} - {title}**

Impact: {what breaks / risk}
Why: {causal path from the change}

Optional section for uncertain concerns:

## Needs verification
- [low] {file}:{line} - {concern} ({what to validate})

## Summary
- P0: N
- P1: N
- P2: N
- P3: N
- Outcome: Blocker | Non-blocking findings | No actionable findings

Use No actionable findings when no credible defects are identified.

What Not to Report

• Style, formatting, naming, or preference-only comments
• Theoretical issues without a plausible failure path
• Pre-existing problems in unchanged code (unless the change introduces the failure path through them)
• Feature requests, enhancement ideas, or missing features
• Duplicate findings for the same underlying issue
• Praise-only notes or non-actionable observations

Tool Defaults

• Do not run linting, type checking, or tests by default.
• Use targeted verification only when necessary to validate a suspected P0/P1 issue that code inspection cannot resolve.
• Focus on semantic review of the change, not automated tooling output.

Anti-Patterns

• Do not report speculation as a finding.
• Do not escalate severity without concrete user, security, or data impact.
• Do not optimize for quantity of findings over accuracy.
• Do not miss cross-file regressions when the diff clearly changes shared behavior.