nicolas-codemate/deep-review

Deep Review Skill

Orchestrates code review by delegating to an isolated code-reviewer agent.

Purpose

The review MUST be performed by a fresh agent with NO prior conversation context. This prevents confirmation bias - an agent that participated in the implementation unconsciously validates its own approach instead of questioning it.

<constraints> - Do not review the code yourself in the current context — confirmation bias from "having seen" the implementation is exactly what we're guarding against. - Delegate to an Agent (`subagent_type: "code-reviewer"`). - The agent receives only self-contained context (diff, conventions, and — in ticket mode — ticket and plan). No conversation history, no implementation reasoning, no debugging context. - The agent prompt must be fully self-contained (all text inline, no file paths to read). - Display the agent's review report verbatim — do not filter or soften findings. </constraints>

Modes

The skill runs in one of two modes, decided by whether a ticket is in scope:

• Ticket mode — a --ticket <id> is passed, OR the conversation is already anchored to a ticket (e.g. invoked by /resolve). The agent is given the ticket and plan so it can judge the change against its intent.
• Standalone mode — no ticket. The change was made inline, outside any ticket flow. The agent judges the diff on its own merits (correctness, regressions, project conventions). This is the "just validate what we modified in the pipe" pass.

If it is ambiguous which mode applies and there is no ticket context, default to standalone mode — do not fabricate or hunt for a ticket.

Inputs

Required context (gathered by YOU, passed inline to the agent):

• Project CLAUDE.md (conventions) — always.
• Git diff of the changes under review — always (see below for how to select it per mode).
• Ticket content (ticket.md text) — ticket mode only.
• Implementation plan (plan.md text) — ticket mode only.

Process

Step 1: Gather Context (you do this)

1. Read project CLAUDE.md from project root -> PROJECT_RULES.

2. Determine the diff to review:

   Ticket mode:

   git diff {base-branch}...HEAD
   git diff {base-branch}...HEAD --stat
   

   Standalone mode: review everything that differs from the base branch, including uncommitted work (the point is to validate what was just changed, which may not be committed yet).

   • Resolve the base branch: use --base if given, else the repo default branch (git symbolic-ref refs/remotes/origin/HEAD → strip prefix; fallback main, then master).
   • Collect committed changes on the branch: git diff {base-branch}...HEAD
   • Collect uncommitted changes: git diff HEAD
   • If the current branch equals the base (e.g. working directly on it), the committed diff is empty — review only git diff HEAD.
   • Also run git status --short so the agent knows about untracked files it should flag if relevant.
   • Combine these into DIFF_CONTENT and a matching DIFF_STATS (--stat on the same ranges). If the combined diff is empty, tell the user there is nothing to review and stop.

3. Ticket mode only: read ticket from .claude-work/{ticket-id}/ticket.md -> TICKET_CONTENT, and plan from .claude-work/{ticket-id}/plan.md -> PLAN_CONTENT.

Step 2: Delegate to Fresh Agent

Build the prompt from the blocks you gathered. In standalone mode, omit the <ticket> and <implementation_plan> blocks entirely and include the <no_ticket> note instead.

Agent:
  subagent_type: code-reviewer
  description: "Fresh code review {ticket-id or 'working diff'}"
  prompt: |
    You are reviewing code changes with fresh eyes.
    You have NO prior knowledge of this implementation.

    # Ticket mode includes these two blocks:
    <ticket>
    {TICKET_CONTENT}
    </ticket>

    <implementation_plan>
    {PLAN_CONTENT}
    </implementation_plan>

    # Standalone mode includes this block instead:
    <no_ticket>
    There is no ticket or plan for this change — it was made outside a ticket flow.
    Do not speculate about intent or invent acceptance criteria. Review the diff on
    its own merits: correctness, regressions, and adherence to the project conventions
    below. Flag anything that looks unfinished or inconsistent with the surrounding code.
    </no_ticket>

    <project_conventions>
    {PROJECT_RULES}
    </project_conventions>

    <diff_stats>
    {DIFF_STATS}
    </diff_stats>

    <diff>
    {DIFF_CONTENT}
    </diff>

    Perform a complete code review following your review process.
    Return the full review report in markdown format.

Step 3: Present Results

Display the review report returned by the agent verbatim.

Step 4: Save Report

• Ticket mode: write the review report to .claude-work/{ticket-id}/review.md.
• Standalone mode: do not write a file by default — display only. Offer to save it if the user wants a record.

Configuration

From .claude/ticket-config.json (applies to ticket mode; standalone mode ignores it):

{
  "review": {
    "enabled": true,
    "auto_fix": false,
    "severity_threshold": "important",
    "block_on_critical": true
  }
}

Status Values

• pending: Review not yet started
• in_progress: Review in progress
• completed: Review finished successfully
• skipped: Review skipped (disabled or no implementation)
• failed: Review encountered an error

Integration

Invoked by /resolve workflow (step 08-review, always ticket mode), or directly by the user in either mode.