pr-writing-review

name	pr-writing-review
description	Extract and analyze writing improvements from GitHub PR review comments. Use when asked to show review feedback, style changes, or editorial improvements from a GitHub pull request URL. Handles both explicit suggestions and plain text feedback. Produces structured output comparing original phrasing with reviewer suggestions to help refine future writing.

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

> **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

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 using the correct path for each commit

Example Analysis Output

After running the script and performing LLM analysis, produce a summary like:

## Style Lessons from PR #123

### Mechanical Fixes

- Fix grammar: "Its" → "It's" (contraction)
- Lowercase generic terms: "Image Generation" → "image generation"
- Remove filler: "the output quality of" → "the quality of"

### Reviewer-Driven Changes

- **"end more enthusiastically"** → Added call-to-action in conclusion
- **"emphasize these are SoTA"** → Changed "latest" to "state-of-the-art"
- **"add blurb about MCP Server"** → Added explanatory paragraph

### Structural Improvements

- Added transition sentence between sections
- Simplified setup instructions (3 sentences → 1)
- Added new bullet point for model flexibility

Limitations

• Only extracts inline PR review comments (not issue comments or the PR description)
• Extremely long files can still be heavy; when that happens, lower --max-file-chars or pass --no-files to keep outputs prompt-friendly

{{currentDate}} {{env}}