# Pr Review Workflow

> Handle PR creation, review comments, feedback, and CI status using GitHub CLI and APIs Use when this capability is needed.

- Skill: `tomevault-io/pr-review-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/pr-review-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/pr-review-workflow/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/pr-review-workflow

---


# Skill: PR Review Workflow

## Activation context

- Creating a PR (see section 5 for PowerShell quoting)
- After pushing commits to a PR branch
- Developer asks about PR comments, review feedback, or CI status

---

## 1. Post-push workflow

After every `git push`, do ALL in order:

1. Fetch review threads (section 2)
2. Summarize and present to developer (section 3)
3. Wait for developer confirmation on which to address
4. Fix, commit, push
5. Reply + resolve each thread (section 4) — these are **inseparable**

**Completion checklist per comment (all required):**

- [ ] Code fix implemented
- [ ] Committed and pushed
- [ ] Replied to comment with commit SHA
- [ ] Thread resolved via GraphQL — immediately after replying

---

## 2. Fetching PR comments

> **⚠️ NEVER use built-in IDE tools** (`github-pull-request_activePullRequest` etc.) — they return stale/cached data. Always use `gh api graphql` directly.

### Primary method: GraphQL reviewThreads

Returns all threads with resolution status, thread IDs, and comment bodies in one call:

```bash
gh api graphql -f query='
  query($owner: String!, $repo: String!, $pr: Int!) {
    repository(owner: $owner, name: $repo) {
      pullRequest(number: $pr) {
        reviewThreads(first: 100) {
          nodes {
            id
            isResolved
            comments(first: 5) {
              nodes { body path author { login } databaseId }
            }
          }
        }
      }
    }
  }
' -f owner="<OWNER>" -f repo="<REPO>" -F pr=<PR>
```

The `id` field on each thread node is the `threadId` needed for resolution.

### REST fallback (only when you need comment IDs for replies)

```bash
gh api repos/<OWNER>/<REPO>/pulls/<PR>/comments --jq "[.[] | {id, path}]"
```

Returns `id` (needed for `in_reply_to` in replies) and `path`. Does NOT show resolution status.

### CI status

```bash
gh pr checks <PR>
```

On failure: `gh run view <run_id> --log-failed` to diagnose.

---

## 3. Assessing comments

### Categorize

Group into: **Actionable** | **Questions** | **Informational** | **Blocking**

Present as a table with file, author, and summary. Wait for developer confirmation before acting.

### Bot comments (`copilot-pull-request-reviewer`, `github-actions`)

- Do not blindly apply — verify against project conventions and codebase context
- Watch for false positives (API format assumptions, inapplicable security warnings, style conflicts with tooling)
- When uncertain, present with your assessment. When wrong, explain why

---

## 4. Responding to comments

### Reply (REST API)

```bash
# -F (not -f) for numeric in_reply_to
gh api repos/<OWNER>/<REPO>/pulls/<PR>/comments \
  -X POST -f body="Fixed in <SHA>." -F in_reply_to=<COMMENT_ID>
```

### Resolve (GraphQL — required after every reply)

```bash
gh api graphql -f query='
  mutation { resolveReviewThread(input: {threadId: "<THREAD_ID>"}) { thread { isResolved } } }
'
```

### Batch resolution

```bash
# Simple loop (copy-paste, replace IDs)
for thread_id in <ID1> <ID2> <ID3>; do
  gh api graphql -f query="mutation { resolveReviewThread(input: {threadId: \"$thread_id\"}) { thread { isResolved } } }"
done

# Or single call (faster for many threads)
gh api graphql -f query='mutation {
  t1: resolveReviewThread(input: {threadId: "<ID1>"}) { thread { isResolved } }
  t2: resolveReviewThread(input: {threadId: "<ID2>"}) { thread { isResolved } }
}'
```

### Disagreeing

Reply with reasoning, then resolve the thread. Do not leave threads open.

---

## 5. Branch Strategy — Avoiding Merge Conflicts

### The problem

Parallel branches created from the same base that modify the same lines will conflict when the first one merges. This is especially painful for **conflict magnets** — files where many PRs converge on the same lines (e.g., mock theme objects in `setup.ts` where every new token addition touches all theme blocks).

### Before creating a new branch

1. Check for open PRs: `GH_PAGER="" gh pr list --limit 20 2>&1`
2. For each open PR, check which files it touches: `gh pr diff <NUMBER> --name-only`
3. If the new work will modify any of the same files, choose a strategy:

| Situation | Strategy |
|-----------|----------|
| New work depends on the open PR | **Stack**: branch from the open PR's branch, not main |
| Same files but independent work | **Wait**: let the open PR merge first, then branch from updated main |
| Overlap is trivial (1-2 lines, different sections) | **Proceed**: create from main, accept minor rebase work |

### Stacking branches

When stacking branch B on top of open PR branch A:

```bash
git switch branch-a
git pull origin branch-a
git switch -c branch-b
# ... work on branch B ...
# When branch A merges into main:
git fetch origin
git rebase origin/main
```

### Known conflict magnets in this project

| File | Why | Frequency |
|------|-----|-----------|
| `mobile/test/setup.ts` | Mock theme objects — every new theme token touches 4+ blocks on adjacent lines | Every theme PR |
| `mobile/components/settings/PreferencesSection.tsx` | Shared imports for settings sections | Settings feature PRs |

Update this table when new patterns emerge.

---

## 6. Creating PRs and Issues

### Avoiding Terminal Escaping Issues

NEVER use heredocs (`<< 'EOF'`) in terminal commands — they corrupt with multi-line content.
NEVER pass backtick-containing text via `--body` — PowerShell uses backticks as escape characters and many shells treat backticks specially; for portability, use `--body-file` instead.

**Correct approach:**
1. Use `create_file` tool to write body to `/tmp/` file
2. Use `--body-file` flag to reference the file
3. Set `GH_PAGER=""` to disable pager (prevents "alternate buffer" issues)

### Creating Issues

```bash
# 1. Create body file using create_file tool (not terminal heredoc)
# 2. Then run:
GH_PAGER="" gh issue create \
  --repo OWNER/REPO \
  --title "feat: Short description" \
  --body-file /tmp/issue-body.md \
  --label "enhancement,area: mobile" 2>&1
```

### Creating PRs

```bash
# Same pattern as issues:
GH_PAGER="" gh pr create \
  --title "feat: Short description" \
  --body-file /tmp/pr-body.md 2>&1
```

### Listing Issues/PRs

Always disable pager to avoid "alternate buffer" output:

```bash
GH_PAGER="" gh issue list --limit 10 2>&1
GH_PAGER="" gh pr list --limit 10 2>&1
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/skanetrails) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->