# Review Deep

> Deep-review a PR or branch with issue and repo context, then fix and commit actionable findings; PR-backed runs push new review commits by default. Use for 'review my changes', 'check this PR', or post-implementation quality/spec review requests. SKIP existing human/bot review comments that need replies/thread resolution; use address-review.

- Skill: `gopherguides/review-deep` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add gopherguides/review-deep`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gopherguides/review-deep/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: gopherguides (https://skillmd.com/u/gopherguides)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gopherguides/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:
<claude-skill-arguments>
$ARGUMENTS
</claude-skill-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`).

```bash
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:

| Configuration | Post-review state |
|---------------|-------------------|
| Default with a detected PR and fixes | Fix, commit, and push; local and PR remote heads must match |
| Default without a PR | Fix and commit locally; do not push |
| `--no-fix` | Review only; do not create a review commit or auto-push |
| `--no-commit` | Leave review-owned fixes in the working tree; auto-push is disabled |
| `--no-push` | Commit review-owned fixes locally and report that the remote is unchanged |
| `--push` | Push explicitly; fail if review-owned fixes are still uncommitted |

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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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

```bash
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):

```bash
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