sr

name	sr
description	Use when asked to review code before merge or review a PR, branch, commit range, task path, or current working tree. Trigger on requests like 'review PR', 'review my changes', 'review this branch', 'is this ready to merge', or other pre-merge review requests. Supports task/spec-aware review when task docs exist. NOT for addressing review comments (use /prc).
argument-hint	["task-path | PR-url | branch | range | deep | no-arg auto-detect"]
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","AskUserQuestion","TodoWrite","Skill","Agent"]

Start Review

Announcement: Begin with: "I'm using the sr skill for universal code review."

Universal review entrypoint for task paths, PRs, branches, explicit ranges, and local working-tree drafts. Resolve the review target first, then only run checks supported by the evidence you actually have.

When to Use

• Pre-merge code review
• "review this PR"
• "review this branch"
• "review my changes"
• "is this ready to merge?"
• Task review when a task directory or spec exists

When NOT to Use

• Addressing review comments -> /prc
• General codebase exploration -> /code-analysis
• Implementation-plan review -> /rip

STEP 1: Resolve Review Target

• Task path -> task
• PR URL or PR number -> pr
• Explicit git range -> range
• Branch name -> branch
• No arguments:
  1. If staged, unstaged, or untracked changes exist -> working-tree
  2. Else if current branch differs from resolved base -> branch
  3. Else ask what to review

STEP 2: Detect Capabilities

Record these fields before dispatching reviewers:

• has_task_doc
• has_spec
• has_committed_snapshot
• can_run_verification
• review_scope

Rules:

• task mode may use task docs and spec compliance
• pr, branch, and range modes do not require task docs
• working-tree mode never requires a clean tree
• set has_committed_snapshot = false for working-tree; set it from resolved SHAs for committed modes
• Never claim spec compliance when no spec artifact exists
• PR descriptions or issue text do not count as spec unless the user explicitly says to treat them as the review baseline
• Cross-AI validation and Linear syncing are optional follow-ups, not default gates

STEP 3: Resolve Base and Diff Context

Prefer base in this order:

1. PR base branch
2. Task-documented base branch
3. Current branch upstream
4. main
5. master

Compute diff context once and share it with all reviewers:

• changed_files
• full_diff
• review_mode
• base_ref
• head_ref
• has_spec

Diff rules:

• task, pr, branch, range: use committed diff from the resolved base or explicit range
• working-tree: use staged plus unstaged local diff, include untracked files in changed_files, set base_ref = HEAD, and set head_ref = working-tree
• Exclude generated files and lockfiles unless the user explicitly wants them reviewed

Do NOT force main...HEAD onto every review mode.

STEP 4: Choose Scope

Use quick only when ALL are true:

• <= 3 changed files
• <= 50 diff lines
• no auth, migrations, infra, build-system, or shared framework changes

Otherwise use full.

Deep (thermo) scope (/sr deep): opt-in structural-quality tier. deep runs everything full does plus the structural-quality-reviewer (STEP 5.3). It is never auto-selected — only the user invokes it via /sr deep.

Auto-suggest deep: after resolving scope, if the diff crosses any structural threshold — a changed file > 1000 lines, > 15 changed files, > 600 changed lines, or a module rename/move — and the user did not request deep, add a one-line recommendation to the review output (alongside the STEP 10 QA recommendation): Deep structural review recommended: <trigger>. Run /sr deep. This is a recommendation, not a blocker — continue with full.

Full-feature scope option (--scope=feature): When reviewing Phase N of a multi-phase task and the task directory contains earlier phases, optionally include the full feature diff (all phases from the earliest base commit to HEAD). Flag files changed in earlier phases but not in the current phase as integration surface — these are where cross-phase bugs hide. Use this when the current phase integrates with prior phases or when the task doc mentions cross-phase dependencies.

STEP 5: Review Pipeline

deep is a superset of full: apply every full-scope rule below, then add the structural pass (5.3).

5.1 Optional Spec Gate

Run spec-compliance-reviewer only when has_spec = true.

If no spec exists, write: Skipped - no task/spec artifact available.

5.2 Core Reviewers

Always run:

• security-code-reviewer
• code-quality-reviewer

Run senior-architecture-reviewer when:

• scope is full, or
• boundaries or dependencies changed, or
• new modules, services, or interfaces were introduced

5.3 Extended Reviewers

In full scope, also run:

• test-coverage-reviewer
• documentation-accuracy-reviewer
• performance-reviewer

In deep scope, additionally run structural-quality-reviewer — a whole-module structural audit (details in its agent file). It writes to <!-- SECTION:structural-quality -->. Never run it in quick or full.

5.4 Targeted Review Passes & Pattern Propagation

Orchestrator-owned inline checks (not subagents) plus a sibling-scan procedure. The trigger table and per-pass checklists — error-path, integration-seams, cross-surface entity — and the pattern-propagation procedure live in references/review-passes.md. Read it now when the diff matches any trigger, run the matching pass, and add findings to key-findings.

For every skipped reviewer, write a one-line reason in that section.

STEP 6: Verification Policy

Verification is evidence, not a prerequisite for starting review.

• task: prefer verification commands from the task doc; otherwise run narrow package checks
• pr, branch, range: run the smallest repo-appropriate checks for touched packages when safe
• working-tree: run only safe local checks; do NOT block review on a dirty tree

If verification is skipped or partial, record it. Missing verification is not passing verification.

STEP 7: Prepare CR File

There is always exactly one Code Review file per review target. Compute cr_file_path:

• task -> <task-directory>/code-review-[feature-name].md
  • Extract [feature-name] from the task directory name by stripping the task-YYYY-MM-DD- prefix (e.g., task-2026-04-02-operations-center → operations-center). If the directory does not match this prefix pattern, use the full directory name as the feature name.
• working-tree -> .claude/reviews/code-review-working-tree-[current-branch].md (or code-review-working-tree.md if detached)
• all other non-task modes -> .claude/reviews/code-review-[target].md (create .claude/reviews/ if missing)

Sanitization: Replace any / or spaces in [current-branch] or [target] with hyphens before constructing the filename.

If cr_file_path already exists (re-review): reuse it. Clear all <!-- SECTION:xxx --> contents back to placeholder text so agents write fresh findings. Do NOT create a second file.

Legacy migration: If cr_file_path does not exist, also check for a legacy Code Review.md (task mode) or Code Review - *.md (other modes) in the same directory. If found, rename it to the new cr_file_path convention before reusing.

If no file exists at all: create it by writing the template from .claude/docs/templates/code-review-template.md.

STEP 8: Dispatch Agents

Pass cr_file_path to every agent so they use File Mode.

Dispatch all agents selected in STEP 5 in a single turn — issue every Agent tool call in the same assistant message. The agents write to disjoint <!-- SECTION:xxx --> markers in cr_file_path, so there are no ordering dependencies (in deep scope this batch also includes structural-quality-reviewer, writing to its own structural-quality markers). Each agent already receives the same full_diff / changed_files context computed once in STEP 3, so the tool calls are independent and safe to batch. Do not dispatch one, wait for it to finish, then dispatch the next; that serializes a parallel workload.

Each agent reads → edits its own section markers only; no agent touches another agent's section.

If an agent fails or times out, write a fallback note into its section: *Review skipped — [agent-name] did not complete.*

Once every dispatched agent has finished, proceed to STEP 9.

STEP 9: Write Verdict

The orchestrator writes the remaining sections that agents do not own:

• review-context — fill from STEP 2 capabilities
• summary — synthesize a 2-5 sentence note from agent findings
• verdict — one of the verdicts below
• key-findings — consolidate actionable findings from all agents. Include every CRITICAL and MAJOR regardless of confidence. For MINOR/INFO, include items marked confidence: high; drop or collapse confidence: low MINOR/INFO into a single "Other low-confidence notes" bullet. Order by severity, then confidence. Structural [OPPORTUNITY] findings (deep scope) go in a dedicated "Structural Opportunities" sub-block — they surface prominently but do NOT count toward the verdict; route them to /prc or a follow-up task.
• coverage — record what was reviewed and what was skipped
• verification — record commands run and results
• metadata — changed files, diff source, reviewers invoked

Use the Edit tool to write each orchestrator section into its markers in cr_file_path. Do NOT overwrite the entire file — agents already wrote their sections.

Verdicts:

• DRAFT REVIEW: working-tree review or no immutable snapshot
• APPROVED: committed snapshot, sufficient coverage, 0 critical, 0 major
• APPROVED WITH NOTES: committed snapshot, 0 critical, 0 major, but verification or coverage is partial
• NEEDS FIXES: any critical or major finding (including structural CRITICAL/MAJOR from deep scope; [OPPORTUNITY] findings never trigger this)

Never return APPROVED for an uncommitted working-tree draft.

STEP 10: QA Gate Recommendation

After the verdict is written, check whether the diff affects user-facing rendering — any file that produces DOM output, styling, or routing state. Use this list as a seed, not a limit: .svelte, .tsx, .jsx, .vue, .html, .astro, .mdx, CSS/SCSS, component stories, route files. When in doubt, treat it as UI. If it qualifies, append a QA recommendation to the review file:

QA recommended: This review includes UI changes. Static code review cannot catch runtime layout, navigation, or user-flow issues. Consider running browser-based QA (manual or automated) before merging.

This is a recommendation, not a blocker. It surfaces the gap between "code looks correct" and "feature works correctly."

Operating Reminders

Three gates are worth re-stating because mis-handling them corrupts the review file:

• One CR file per review target — reuse and clear existing markers instead of creating a second file (see STEP 7).
• Pass cr_file_path to every dispatched agent so they write in File Mode (see STEP 8).
• Use Edit, not Write, on cr_file_path after agents have populated their sections — a full overwrite destroys their work (see STEP 9).

Common Rationalizations

The shortcuts that turn a review into a rubber stamp:

Rationalization	Reality
"The implementer says it's done and tested — I'll trust the summary"	Review reads the code, not the claim. Verify against the diff; never sign off on a self-report.
"It looks fine, I'll approve"	"Looks fine" is not a finding. Either name what you verified, or read deeper — an empty review is worse than no review.
"I'll only look at the changed lines"	Cross-phase and integration bugs live in files the diff touches indirectly. Use --scope=feature when a change integrates with prior work (STEP 4).
"No spec artifact, so I'll claim it matches the spec anyway"	Never assert spec compliance without a spec artifact — emit Skipped - no task/spec artifact available (STEP 6).
"Lots of nits — I'll mark them all CRITICAL to be safe"	Severity inflation trains the author to ignore you. Label honestly: Nit/Optional/FYI vs MAJOR/CRITICAL.

Red Flags

• Writing a verdict without having read the actual changed code.
• Approving with zero findings and zero stated verification.
• Claiming spec compliance when no spec/task artifact exists.
• Every finding tagged the same severity (all critical, or all nits).
• Reviewing only the literal diff when the change clearly integrates with earlier phases.

Related Skills

Need	Use
Address review feedback	/prc
Formal tracked implementation	/si
Explore code before reviewing	/code-analysis