Review Deep

Deep Review: Full-Context Code Review + Fix

Plugin Resource Resolution

<PLUGIN_ROOT> is notation. Replace it with a concrete absolute plugin root before every resource read or command:

• Codex: Start from the directory containing the absolute selected SKILL.md path, then ascend two directories (skills/<name> -> plugin root).
• Claude Code: Bind it to the injected ${CLAUDE_PLUGIN_ROOT} value.

Performs a thorough code review with full PR/issue context, then fixes all actionable findings. Combines the depth of spec review, quality review, and Go-specific analysis in a single pass.

Before requesting decisions or delegating work, read <PLUGIN_ROOT>/lib/driver-interaction.md and follow its cross-platform capability-binding rules.

Read <PLUGIN_ROOT>/lib/decision-gates.md before resolving review coverage or post-review actions.

Bind the invocation arguments as SKILL_ARGS for $go-workflow:review-deep by reading <PLUGIN_ROOT>/lib/skill-arguments.md with this Claude Code compatibility payload: $ARGUMENTS

Step 0: Parse Arguments

Parse SKILL_ARGS to extract:

• Bare numeric value: PR number (e.g., $go-workflow:review-deep 42)
• --issue <N>: Use specific issue as context (no PR required)
• --post: Auto-post findings to PR as a comment (skip asking)
• --scope <hint>: Focus area for the review (e.g., "error handling", "concurrency")
• --no-fix: Review only; do not edit files
• --no-commit: Apply fixes but leave review-owned changes uncommitted
• --push: Push the resulting local HEAD, including for a branch-only run
• --no-push: Never push; return the local and remote head state
• Remaining text after flags: treated as scope hint

Store as PR_ARG, ISSUE_ARG, AUTO_POST (default: false), SCOPE_HINT, FIX_CHANGES (default: true), COMMIT_CHANGES (default: true), and PUSH_CHANGES (default: auto).

PR_ARG=""
ISSUE_ARG=""
AUTO_POST=false
SCOPE_HINT=""
FIX_CHANGES=true
COMMIT_CHANGES=true
PUSH_CHANGES=auto
ARGS="$SKILL_ARGS"

while [ -n "$ARGS" ]; do
  case "$ARGS" in
    --issue\ *)
      ARGS="${ARGS#--issue }"
      ISSUE_ARG="${ARGS%% *}"
      ARGS="${ARGS#"$ISSUE_ARG"}"
      ARGS="${ARGS# }"
      ;;
    --post*)
      AUTO_POST=true
      ARGS="${ARGS#--post}"
      ARGS="${ARGS# }"
      ;;
    --scope\ *)
      ARGS="${ARGS#--scope }"
      SCOPE_HINT="$ARGS"
      ARGS=""
      ;;
    --no-fix*)
      FIX_CHANGES=false
      ARGS="${ARGS#--no-fix}"
      ARGS="${ARGS# }"
      ;;
    --no-commit*)
      COMMIT_CHANGES=false
      ARGS="${ARGS#--no-commit}"
      ARGS="${ARGS# }"
      ;;
    --no-push*)
      PUSH_CHANGES=false
      ARGS="${ARGS#--no-push}"
      ARGS="${ARGS# }"
      ;;
    --push*)
      PUSH_CHANGES=true
      ARGS="${ARGS#--push}"
      ARGS="${ARGS# }"
      ;;
    [0-9]*)
      PR_ARG="${ARGS%% *}"
      ARGS="${ARGS#"$PR_ARG"}"
      ARGS="${ARGS# }"
      ;;
    *)
      SCOPE_HINT="$ARGS"
      ARGS=""
      ;;
  esac
done

echo "PR_ARG=$PR_ARG ISSUE_ARG=$ISSUE_ARG AUTO_POST=$AUTO_POST SCOPE_HINT=$SCOPE_HINT FIX_CHANGES=$FIX_CHANGES COMMIT_CHANGES=$COMMIT_CHANGES PUSH_CHANGES=$PUSH_CHANGES"

Action Contract

Fix, commit, and push are separately controllable:

PR-backed runs push newly created review commits by default. Branch-only runs require --push. Every run returns a structured commit/push result with local and remote head SHAs; a push failure is an incomplete review, never success.

Step 1: Detect Scope & Base Branch

If PR_ARG is set, use it directly. Otherwise, auto-detect from the current branch using three strategies in order — fall through when each returns empty.

Strategy 1 — current branch:

PR_JSON=$(gh pr view --json number,title,body,state,baseRefName,headRefName,closingIssuesReferences --jq '.' 2>/dev/null)

Strategy 2 — match HEAD commit against open PRs:

if [ -z "$PR_JSON" ]; then
  HEAD_SHA=$(git rev-parse HEAD 2>/dev/null)
  PR_NUM=$(gh pr list --search "$HEAD_SHA" --state open --json number --jq '.[0].number' 2>/dev/null)
  if [ -n "$PR_NUM" ] && [ "$PR_NUM" != "null" ]; then
    PR_JSON=$(gh pr view "$PR_NUM" --json number,title,body,state,baseRefName,headRefName,closingIssuesReferences 2>/dev/null)
  fi
fi

Strategy 3 — match HEAD against any (open/closed/merged) PRs:

if [ -z "$PR_JSON" ]; then
  HEAD_SHA=$(git rev-parse HEAD 2>/dev/null)
  PR_NUM=$(gh pr list --search "$HEAD_SHA" --state all --limit 5 --json number --jq '.[0].number' 2>/dev/null)
  if [ -n "$PR_NUM" ] && [ "$PR_NUM" != "null" ]; then
    PR_JSON=$(gh pr view "$PR_NUM" --json number,title,body,state,baseRefName,headRefName,closingIssuesReferences 2>/dev/null)
  fi
fi

Extract PR number and base branch:

if [ -n "$PR_JSON" ]; then
  PR_NUM=$(echo "$PR_JSON" | jq -r '.number')
  BASE_BRANCH=$(echo "$PR_JSON" | jq -r '.baseRefName')
  PR_HEAD_BRANCH=$(echo "$PR_JSON" | jq -r '.headRefName')
  echo "Found PR #$PR_NUM (base: $BASE_BRANCH, head: $PR_HEAD_BRANCH)"
else
  BASE_BRANCH=$( (git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' | grep .) || (git remote show -n origin 2>/dev/null | grep 'HEAD branch' | sed 's/.*: //' | grep .) || echo "main" )
  PR_HEAD_BRANCH=""
  echo "No PR found. Using base branch: $BASE_BRANCH"
fi

Display a brief summary of what was detected.

Step 2: Gather Full Context

Read context-gathering.md and execute the procedure end-to-end:

• PR metadata (title, body, state, comments, reviews)
• Linked issues (title, body, labels, comments)
• Review threads (unresolved, with file paths and line numbers)
• Inline review comments
• Pending reviews (CHANGES_REQUESTED)
• Repo guidelines (AGENTS.md or CLAUDE.md)

If --issue N was provided instead of a PR, fetch just the issue context. If no PR and no issue, proceed with diff-only review (no requirement verification, no review-comment status).

context-gathering.md includes the size guard — if combined context exceeds ~6000 characters, use summary format.

Step 3: Generate Diff and Coverage Plan

Based on detected scope:

• Changes vs base branch (default when PR detected): git diff ${BASE_BRANCH}...HEAD
• Uncommitted changes (no PR + uncommitted changes exist): git diff HEAD plus untracked files via git ls-files --others --exclude-standard
• Explicit PR_ARG: always use changes vs base branch

DIFF=$(git diff "${BASE_BRANCH}...HEAD")
REVIEW_BASE="$BASE_BRANCH"
REVIEW_BACKEND=agent
REVIEW_CONCURRENCY=auto

Read ../../lib/review-planning.md, run the shared planner, display its coverage plan, and follow it through the final coordinated pass. Do not interrupt solely because of raw diff size. Preserve SCOPE_HINT as review emphasis.

Step 4: Static Analysis

If a Go project is detected (go.mod exists):

CHANGED=$(git diff --name-only "${BASE_BRANCH}...HEAD" | grep '\.go$')
if [ -n "$CHANGED" ]; then
  echo "$CHANGED" | xargs -I{} dirname {} | sort -u | xargs go vet 2>&1 || true
  echo "$CHANGED" | xargs -I{} dirname {} | sort -u | xargs staticcheck 2>&1 || true
  echo "$CHANGED" | xargs -I{} dirname {} | sort -u | xargs go test -race -count=1 2>&1 || true
fi

Static-analysis failures are informational — they feed into the review, not block it.

When review includes browser screenshots, read <PLUGIN_ROOT>/lib/screenshot-evidence.md before capturing. Initialize the manifest and record every inspected route/capture, including failures, for the Step 7 report. This does not add browser testing to reviews without visual work.

Step 5: Perform Review

Read review-criteria.md for the full criteria, the Quality Score Rubric, the confidence-scoring guide, and the breaking-change detection block. Apply all criteria to the diff with the gathered context.

Process:

1. Review every unit from the Step 3 coverage plan against every criterion in review-criteria.md.
2. Cross-reference with requirements (when PR/issue context is available): each acceptance criterion → implementation → tests; check for missing requirements and scope creep.
3. For each existing review thread, mark whether it appears addressed in the current diff.
4. Include the Step 4 static-analysis results.
5. Detect breaking changes in exported symbols (grep recipe in review-criteria.md).
6. Run the plan's cross-cutting pass, then verify, deduplicate, and rank findings against the checkout before Step 6.

For the exact findings-table layout, spec-compliance table, review-comments-status table, and the recommendation values — Read output-format.md.

Step 6: Fix Findings

Read fix-and-verify.md and follow it end-to-end. Highlights:

• When FIX_CHANGES=false, skip file edits, test generation, and verification for fixes; continue to the post-fix action result
• Process findings in priority order (P0 → P3)
• Auto-skip priority 3 AND confidence < 0.5 (nit noise)
• Make minimal fixes; track which fixes are testable
• Delegate fresh-context reviewers in parallel when 3+ findings target different files
• Generate tests for testable fixes; verify build/test/lint pass
• Pass only review-owned files to the post-fix helper
• Apply COMMIT_CHANGES and PUSH_CHANGES independently
• Treat any commit, push, or remote-head verification failure as incomplete

Step 7: Post-Review Summary & Actions

Display the final summary:

## Review Complete

- **Findings reported:** <n>
- **Findings fixed:** <n>
- **Findings skipped:** <n> (with reasons)
- **Files changed:** <list>
- **Quality Score:** <n>/100
- **All verifications passed:** yes/no
- **Commit result:** created / none / skipped
- **Push result:** pushed / skipped
- **Local head:** <sha>
- **Remote head:** <sha or empty when unavailable>
- **Recommendation:** APPROVE / REQUEST_CHANGES / COMMENT

Use the exact structured result from review-deep-post-fix.sh. If that helper failed, do not display Review Complete, post an approval, or imply that PR fixes reached the remote.

Post to PR

If AUTO_POST is true and a PR was detected, post immediately using the shared screenshot-evidence poster and formatting from output-format.md.

If AUTO_POST is false and a PR was detected, resolve a driver-resolvable gate. Post only when the original request explicitly asks for a PR comment; otherwise keep the report in the current response. State Decision, Evidence, and Rationale. Do not request input for this reversible delivery choice.

Further Reading

• context-gathering.md — PR/issue/review-thread fetching, repo-guideline detection, size guard
• review-criteria.md — full review criteria, Go idiom checks, Quality Score Rubric, confidence scoring, breaking-change detection
• fix-and-verify.md — fix iteration, parallel dispatch, test generation, verification, commit, and push
• ../../scripts/review-deep-post-fix.sh — deterministic owned-file commit, optional push, and remote-head verification
• output-format.md — findings table, spec-compliance table, review-comments-status table, PR-comment template
• ../../lib/review-planning.md — shared adaptive coverage planning and finding coordination