home / skills / dagster-io / erk / pr-operations

pr-operations skill

safe

This skill helps you manage PR review comments and resolve threads using erk exec commands, ensuring correct thread handling and streamlined collaboration.

npx playbooks add skill dagster-io/erk --skill pr-operations

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

4.8 KB

---
name: pr-operations
description: Use when working with PR review comments, resolving threads, or replying to discussion comments. Essential for understanding the correct erk exec commands for PR thread operations.
---

# PR Operations Skill

## Core Rule

> **CRITICAL: Use ONLY `erk exec` Commands for PR Thread Operations**
>
> - ❌ DO NOT use raw `gh api` calls for thread operations
> - ❌ DO NOT use `gh pr` commands directly for thread resolution
> - ✅ ONLY use `erk exec` commands listed below
>
> The `erk exec` commands handle thread resolution correctly. Raw API calls only reply without resolving.

## Quick Reference

| Command                       | Purpose                         | Key Point                      |
| ----------------------------- | ------------------------------- | ------------------------------ |
| `get-pr-review-comments`      | Fetch unresolved review threads | Returns threads with line info |
| `get-pr-discussion-comments`  | Fetch PR discussion comments    | Returns top-level comments     |
| `resolve-review-thread`       | Reply AND resolve a thread      | Does both in one operation     |
| `reply-to-discussion-comment` | Reply to discussion comment     | For non-code feedback          |
| `post-pr-inline-comment`      | Post new inline comment         | Creates new review thread      |

## When to Use Each Command

### Fetching Comments

```bash
# Get all unresolved review threads (code comments)
erk exec get-pr-review-comments

# Get all discussion comments (top-level PR comments)
erk exec get-pr-discussion-comments

# Include resolved threads (for reference)
erk exec get-pr-review-comments --all
```

### Resolving Review Threads

```bash
# Always use this to resolve review threads - it replies AND resolves
erk exec resolve-review-thread --thread-id "PRRT_abc123" --comment "Fixed in commit abc1234"
```

### Replying to Discussion Comments

```bash
# For PR discussion comments (not code review threads)
erk exec reply-to-discussion-comment --comment-id 12345 --reply "**Action taken:** Updated the docs as requested."
```

## Common Mistakes

| Mistake                                        | Why It's Wrong                | Correct Approach                      |
| ---------------------------------------------- | ----------------------------- | ------------------------------------- |
| Using `gh api repos/.../comments/{id}/replies` | Only replies, doesn't resolve | Use `erk exec resolve-review-thread`  |
| Using `gh pr comment`                          | Doesn't resolve threads       | Use `erk exec resolve-review-thread`  |
| Skipping resolution for outdated threads       | Threads stay open in PR       | Always resolve, even if already fixed |
| Generic replies like "Noted"                   | Not useful for PR history     | Include investigation findings        |

## Replying vs Resolving

> **IMPORTANT: Replying ≠ Resolving**
>
> - **Replying** (via raw `gh api .../replies`): Adds a comment but thread stays OPEN
> - **Resolving** (via `erk exec resolve-review-thread`): Adds a comment AND marks thread as RESOLVED
>
> Always use `erk exec resolve-review-thread` - it does both in one operation.

## Comment Classification Model

When analyzing PR feedback, classify comments by complexity and group into batches.

### Complexity Categories

- **Local fix**: Single comment → single location change (e.g., "Fix typo", "Add type annotation")
- **Multi-location**: Single comment → changes in multiple spots in one file
- **Cross-cutting**: Single comment → changes across multiple files
- **Related**: Multiple comments that inform a single unified change

### Batch Ordering

Process batches from simplest to most complex:

| Batch | Complexity                 | Description                         | Example                                                   |
| ----- | -------------------------- | ----------------------------------- | --------------------------------------------------------- |
| 1     | Local fixes                | One file, one location per comment  | "Use LBYL pattern at line 42"                             |
| 2     | Single-file multi-location | One file, multiple locations        | "Rename this variable everywhere in this file"            |
| 3     | Cross-cutting              | Multiple files affected             | "Update all callers of this function"                     |
| 4     | Complex/Related            | Multiple comments inform one change | "Fold validate into prepare" + "Use union types for this" |

**Note**: Discussion comments requiring doc updates go in Batch 3 (cross-cutting).

### Batch Confirmation Flow

- **Batch 1-2 (simple)**: Auto-proceed without confirmation
- **Batch 3-4 (complex)**: Show plan and wait for user approval

## Detailed Documentation

For complete command documentation including JSON output formats, options, and examples:

@references/commands.md

Overview

This skill helps engineers manage pull request review threads and discussion comments using the erk exec command set. It enforces using erk exec for replies and resolutions so threads are properly closed and PR history stays accurate. Use it to fetch unresolved threads, reply to discussion comments, create inline comments, and resolve review threads in one step.

How this skill works

The skill maps common PR thread operations to specific erk exec commands that both post comments and update thread state. It fetches unresolved review threads or top-level discussion comments, posts inline feedback, and — critically — resolves threads using erk exec resolve-review-thread so threads are marked resolved. Avoid raw gh api or gh pr commands for thread resolution because they only add replies and do not change thread status.

When to use it

When collecting all unresolved code review threads to plan work
When replying to PR discussion comments that are not tied to code lines
When you need to post a new inline comment that should create a review thread
When you must reply and mark a review thread resolved in one operation
When batching review fixes from simple to complex changes

Best practices

Always use erk exec resolve-review-thread to reply and resolve; never use gh api or gh pr for resolving
Fetch unresolved threads first with erk exec get-pr-review-comments to avoid missed items
Classify comments into batches (local, multi-location, cross-cutting, related) and process from simplest to most complex
Auto-proceed on Batch 1–2 changes; require an explicit plan and approval for Batch 3–4
When resolving, include concise action notes and reference commits or PR change IDs for clear history

Example use cases

Audit PR and list unresolved code review threads: erk exec get-pr-review-comments
Reply to a top-level discussion comment: erk exec reply-to-discussion-comment --comment-id 12345 --reply "Action taken: updated docs"
Post a new inline comment to start a review thread: erk exec post-pr-inline-comment --line 42 --comment "Consider adding a type check"
Resolve a review thread after fixing code: erk exec resolve-review-thread --thread-id PRRT_abc123 --comment "Fixed in commit abc1234"
Process a batch of typos and small fixes automatically, then present a plan for cross-cutting changes for approval

FAQ

Why not use gh api or gh pr commands to resolve threads?

Those raw GH methods add replies but do not mark review threads as resolved. Only erk exec resolve-review-thread both replies and marks the thread resolved.

How should I order multiple review comments?

Classify comments into batches: local fixes first, then single-file multi-location, cross-cutting, and related/complex. Auto-apply simple batches and request approval for complex batches.