/github-pr

description: GitHub PR review lifecycle - analyze, discuss, post inline comments, follow-up, respond, approve
argument-hint: "[PR-url-or-number|--respond|--follow-up|--approve|--merge|--status|--cancel]"

GitHub PR Review Lifecycle

Full GitHub PR review lifecycle: analyze code, discuss findings with user, post inline comments, follow-up on fixes, approve or request changes.

**GitHub only** (the full posting lifecycle). This command drives inline comments / follow-up / approve / merge exclusively via the `gh` CLI. For **Bitbucket**, `/lets:review <PR>` already reviews a PR end to end (fetch + diff + discussion + summary post via `bbb`); only the inline/approve/merge lifecycle here stays GitHub-only for now. `LETS_PR_FLOW=local` users finish tasks via `/lets:done`.

**Requires:** `gh` CLI installed and authenticated.

> **IMPORTANT:** If the spec below invokes any deferred tool (e.g. `AskUserQuestion`), you MUST load and call it as specified. Never skip the call, never substitute a default answer of your own — the tool invocation is part of the contract. This is critical.

Usage

/lets:github-pr <PR-url-or-number>     # Start new review
/lets:github-pr                        # Resume from saved state
/lets:github-pr --follow-up            # Check if fixes addressed comments
/lets:github-pr --respond [PR]         # Author: triage review comments, fix, reply
/lets:github-pr --approve              # Approve PR
/lets:github-pr --merge                # Merge PR
/lets:github-pr --status               # Show current review state
/lets:github-pr --cancel               # Clean up state, abandon review

Step 1: Detect Mode

Verify gh CLI

gh auth status 2>&1 || echo "gh not authenticated"

If gh not available or not authenticated, stop: "gh CLI required. Run `gh auth login`."

Parse argument

Interpret user intent:

• PR URL or number -> extract PR number
• `--follow-up` -> Phase 3
• `--respond` -> Phase R (author respond)
• `--approve` -> Phase 4
• `--merge` -> merge only
• `--status` -> show state and exit
• `--cancel` -> clean up state and exit
• No argument, no flag -> check for existing state files

Check for existing state

LETS_PROJECT_ROOT=$(git rev-parse --show-toplevel)
PR_DIR="$LETS_PROJECT_ROOT/.lets/execution/pr-{number}"
STATE_FILE="$PR_DIR/review.json"

--status flag (exit early)

If --status: read state file, show progress summary (phase, findings count, posted status), exit. If no state file: "No active PR review. Run `/lets:github-pr <PR>` to start one."

--cancel flag (cleanup and exit)

If --cancel: 1. Delete PR folder: `rm -rf "$PR_DIR"` (removes state + all temp files) 2. If `stashed: true` in state, warn: "You have a stash from before the PR review. Run `git stash pop` to restore." 3. Switch back to previous_branch if stored 4. Inform user, exit.

Route to phase

**State guard:** If `--follow-up`, `--approve`, `--merge`, or `--respond` is specified but no state file exists: 1. If a PR number is also provided (e.g., `/lets:github-pr --approve 2`), create a minimal state from `gh pr view`:

   REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner) || { echo "ERROR: gh repo view failed - check 'gh auth status'"; exit 1; }
[ -z "$REPO" ] && { echo "ERROR: gh repo view returned empty REPO"; exit 1; }
   gh pr view <PR> --json title,headRefOid,headRefName,baseRefName

Write minimal state (pr_number, repo, title, branch, head_sha, findings: [], findings_posted: false) and continue.

For `--respond` specifically, create a minimal response state (not review state):

• If PR number provided: fetch PR info, create `$PR_DIR/response.json`, continue to Phase R
• If no PR number: check for existing `pr-[0-9]*/response.json` files, or stop

2. If no PR number - stop: "No active PR review found. Run `/lets:github-pr <PR>` to start one."

| State | Action | |-------|--------| | No state file, PR number given | Phase 1 (new review) | | State exists, findings_posted: false | Phase 2 (discuss & post) | | State exists, findings_posted: true, new commits since head_sha | Phase 3 (follow-up) | | State exists, findings_posted: true, no new commits | Show status, ask what to do | | --follow-up flag (state required) | Phase 3 | | --approve flag (state required) | Phase 4 | | --respond flag (PR number or existing state) | Phase R | | --merge flag (state required) | Merge only (Step 5.4) |

No argument, no flag

Look for existing state files:

LETS_PROJECT_ROOT=$(git rev-parse --show-toplevel)
ls -d "$LETS_PROJECT_ROOT/.lets/execution/pr-"[0-9]*/ 2>/dev/null

For each found folder, check which state files exist:

• `review.json` only -> resume review (Phase 2/3/4)
• `response.json` only -> resume respond (Phase R)
• Both exist -> AskUserQuestion: "PR #{number} has both review and response state. Resume as reviewer or author?"
• Multiple PR folders -> AskUserQuestion which PR to resume
• None -> ask user for PR number

Step 2: Phase 1 - Analyze

2.1 Get PR info

gh pr view <PR> --json state,isDraft,title,body,additions,deletions,changedFiles,headRefOid,headRefName,baseRefName

Skip if: closed or draft. Warn if trivial (< 10 lines changed).

PR size check - if additions + deletions > 5000 or changedFiles > 50:

AskUserQuestion(
  questions=[{
    question: "Large PR ({additions}+ {deletions}- across {files} files). How to proceed?",
    header: "Large PR",
    options: [
      { label: "Full review", description: "Review everything" },
      { label: "Focus", description: "Pick specific files or areas" },
      { label: "Cancel", description: "Too large, skip" }
    ],
    multiSelect: false
  }]
)

2.2 Detect active task (before branch switch)

Resolve task-id now - after checkout the branch name changes to the PR branch.

Use the **detect-task** skill to find the active task: `Skill(skill: "lets:detect-task")`. If ambiguous or not found: skip the tracke