pr-writing-review

# PR Writing Review

Extract editorial feedback from GitHub PRs to learn from review improvements.

## Prerequisites

- **GitHub CLI**: `gh` installed
- **Authenticated `gh` session**: `gh auth status` should show you’re logged in
  - For private repos, your token needs appropriate scopes (typically `repo`).
- **Python**: 3.12+
- **uv** (recommended): https://github.com/astral-sh/uv

## Division of Labor

| Tool              | Responsibility                                                          |
| ----------------- | ----------------------------------------------------------------------- |
| **Python script** | API calls, parsing, file tracking across renames, structured extraction |
| **LLM analysis**  | Pattern recognition, paragraph comparison, style lesson synthesis       |

## Quick Start

```bash

> **All paths are relative to the directory containing this SKILL.md file.**
> Before running any script, first `cd` to that directory or use the full path.

# Get suggestions and feedback
uv run scripts/extract_pr_reviews.py <pr_url>

# Get full first→final comparison for deep analysis
uv run scripts/extract_pr_reviews.py <pr_url> --diff

# Same as above, but cap each FIRST/FINAL dump to 2k chars for LLM prompting
uv run scripts/extract_pr_reviews.py <pr_url> --diff --max-file-chars 2000
```

## Workflow

### Step 1: Extract with `--diff`

```bash
uv run scripts/extract_pr_reviews.py https://github.com/org/repo/pull/123 --diff
```

This outputs:

1. **Explicit Suggestions** — exact before/after text from `suggestion` blocks (supports multiple suggestion blocks per comment)
2. **Reviewer Feedback** — plain text comments (the "why" behind changes)
3. **File Evolution** — first draft and final version of each text file

> Tip: add `--max-file-chars 2000` to keep each FIRST/FINAL dump lightweight, or pair `--diff` with `--no-files` if you only need the suggestion/feedback summaries.

### Step 2: Analyze the Output

With the script output, perform this analysis:

#### A. Catalog the Explicit Suggestions

Create a table of mechanical fixes:

| Pattern        | Original           | Fixed              |
| -------------- | ------------------ | ------------------ |
| Grammar        | "Its easier"       | "It's easier"      |
| Filler removal | "using this way"   | "this way"         |
| Capitalization | "Image Generation" | "image generation" |

#### B. Map Feedback to Changes

For each reviewer feedback comment:

1. Find the relevant section in FIRST DRAFT
2. Find the same section in FINAL VERSION
3. Document what changed and why

Example:

> **Feedback:** "would be nice to end more enthusiastically"
>
> **First draft:** "...it's simple to add new tools to Claude and use them straight away."
>
> **Final:** "...Let us know what you find and create in the comments below!"
>
> **Lesson:** End blog posts with a call-to-action

#### C. Paragraph-by-Paragraph Comparison

Compare FIRST DRAFT to FINAL VERSION section by section:

- What was added?
- What was removed?
- What was reworded?
- What structural changes were made?

#### D. Synthesize Style Patterns

Group findings into categories:

| Category      | Patterns Found                                   |
| ------------- | ------------------------------------------------ |
| **Clarity**   | Passive→active, shorter sentences, remove filler |
| **Precision** | Vague→specific, "Create"→"Generate"              |
| **Tone**      | Added enthusiasm, call-to-action endings         |
| **Structure** | Added transitions, better section flow           |
| **Grammar**   | its/it's, subject-verb agreement                 |
| **Content**   | Added links, examples, context                   |

## Script Options

> 📁 **All paths are relative to the directory containing this SKILL.md file.**

| Flag                 | Output                                                                           | Use Case                                                    |
| -------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| _(none)_             | Suggestions + feedback                                                           | Quick review of what reviewers said                         |
| `--diff`             | Adds FIRST/FINAL file dumps to the default output                                | Deep analysis of how the author responded                   |
| `--max-file-chars N` | Truncates each FIRST/FINAL block to _N_ chars (appends `...[truncated X chars]`) | Keep prompts within LLM token limits                        |
| `--no-files`         | Suppresses FIRST/FINAL dumps even when `--diff` is set                           | When you only need explicit suggestions + reviewer feedback |
| `--json`             | Raw JSON (includes `file_evolutions` when `--diff` without `--no-files`)         | Programmatic processing                                     |

> Input formats: pass either a full PR URL, `owner/repo PR_NUMBER`, or `owner repo PR_NUMBER`.

## Output Structure

### Default Output

- **Writing Suggestions**: Grouped by reviewer, shows original→suggested text (fenced blocks) along with any reviewer note and a permalink back to GitHub
- **Reviewer Feedback**: Plain comments without code suggestions, each tagged with its GitHub link

### With `--diff`

- **Explicit Suggestions**: Compact before/after pairs, reviewer notes, and GitHub permalinks in one place
- **Reviewer Feedback**: Numbered list of requests (same as default view)
- **File Evolution**: FIRST DRAFT and FINAL VERSION for each `.md`/`.txt`/`.rst`/`.mdx` file; add `--max-file-chars` to truncate each block with a visible `...[truncated X chars]` indicator

## Handling File Renames

The script traces files through renames by:

1. Checking each commit for rename operations
2. Building a path history (e.g., `claudeimages.md` → `claude-images.md` → `claude-and-mcp.md`)
3. Fetching content usin