codingthefuturewithai/teamcraft-jcg:pr-review

Goal

A reviewer conducts a complete pull request review — reading the diff, understanding the implementation in context, engaging with existing discussion threads, leaving review comments, and deciding to approve or request changes — entirely within Claude Code, without opening the GitHub UI.

Hard Constraints

• The PR number comes from $ARGUMENTS. If not provided, ask.
• Never auto-approve or auto-merge. Every consequential action — approving, merging, requesting changes — requires explicit instruction from the reviewer.
• Use git (Bash) to understand codebase context beyond what the PR diff alone shows. The diff tells what changed; the codebase tells why it matters.
• Human is the authority on what merges. Surface findings and engage with the reviewer. Do not decide.
• All GitHub interactions go through the gh CLI only. All PR operations run via Bash: gh pr view [PR-number], gh pr diff [PR-number], gh pr view [PR-number] --comments, gh pr comment [PR-number] --body "...", gh pr review [PR-number] --approve, gh pr merge [PR-number], gh pr edit [PR-number].
• Thread resolution is not available via gh CLI. GitHub has no CLI equivalent for resolving review threads. After the review is complete, instruct the reviewer to resolve addressed threads in the GitHub UI manually. This is a known capability gap, not an error.

Identify the Project

Read .teamcraft/project.md if it exists — it contains the GitHub repo (owner/repo). If not, run git remote -v via Bash to identify the GitHub repo from the remote URL. No project listing tool is needed.

Load the PR

Fetch the PR details via gh pr view [PR-number] --json number,title,body,headRefName,baseRefName,state,isDraft via Bash. Read it completely: title, description, source branch, target branch, state, linked Jira issue key (from description), and any acceptance criteria the description contains. If the PR description references a Jira issue key (e.g., PROJ-42), note it for context — the original requirements and acceptance criteria belong in the reviewer's picture.

Fetch the diff via gh pr diff [PR-number] via Bash. Fetch existing comments via gh pr view [PR-number] --comments via Bash. Read both in full before presenting anything to the reviewer.

Orient the Reviewer Locally

Check the current local branch. If the reviewer is not already on the PR's source branch, offer to check it out:

"You're currently on [branch]. Want me to check out [source-branch] so you can view the code locally in your editor?"

Wait for their answer. Check it out if they say yes. A reviewer seeing the code in their editor alongside the diff has a better picture than the diff alone.

Understand the Implementation in Context

Read the changed files in the local codebase alongside the diff. The diff shows what changed; the surrounding code shows what it changed relative to. Use git log on the source branch via Bash to understand the commit sequence and how the implementation evolved.

Look for what the automated analysis (code health and security review, if it ran) already flagged. CLAUDE.md and .claude/rules/ contain team conventions — read them to understand what this codebase expects and whether the implementation follows it.

Present the PR to the Reviewer

Synthesize the PR for the reviewer — not a raw diff dump. Cover:

What this PR delivers — a clear statement of what was built, referencing the linked Jira issue and acceptance criteria.

What changed — the meaningful changes, grouped by area or concern. Not a line-by-line recitation. The reviewer can drill into specifics; start with the picture.

Existing discussion — any open comments or threads already in the PR that the reviewer should be aware of.

Your initial read — areas that warrant closer attention: logic that looks unusual, missing edge case handling, anything that doesn't align with team conventions, test coverage gaps, or any concerns the diff alone raises.

Then stop and let the reviewer drive.

Engage the Review

The reviewer leads from here. Support whatever they need:

• Drill into specific files, functions, or lines on request
• Respond to or add to existing discussion threads via gh pr comment [PR-number] --body "..." via Bash — present any comment for confirmation before posting
• Leave review comments on specific concerns via gh pr review [PR-number] --comment --body "..." via Bash — present the draft for confirmation before posting
• Answer questions about what the code does or why it was written a particular way (inferred from the implementation and commit history)

Actions Available

When the reviewer is ready to act, offer the options that apply:

Approve — if the reviewer confirms they are approving, run gh pr review [PR-number] --approve via Bash. Confirm once before acting.

Request changes — run gh pr review [PR-number] --request-changes --body "..." via Bash with a summary of the reviewer's concerns. Present the draft body for review before posting.

Merge — if the reviewer instructs a merge, check pipeline status first via gh run list --branch [source-branch] via Bash. Present the current state and get explicit confirmation before running gh pr merge [PR-number] via Bash.

Close without merging — if the reviewer decides the PR should not proceed, update the PR with a closing comment via gh pr comment [PR-number] --body "..." and close it via gh pr close [PR-number] via Bash. Confirm before acting.

No action happens without explicit reviewer instruction. No action happens without confirmation of what will be done before it is done.

Thread Resolution

After completing any round of review, instruct the reviewer:

"To mark addressed threads as resolved, open the PR in the GitHub UI and resolve each thread. GitHub does not support thread resolution via the CLI — this step must be done in the browser."

This is expected behavior, not a workaround. Note which threads the reviewer indicated are addressed so they know which ones to resolve.