gabrielmoreira PR Writing Review
Extract editorial feedback from GitHub PRs to learn from review improvements.
Prerequisites
- GitHub CLI:
ghinstalled - Authenticated
ghsession:gh auth statusshould show you’re logged in- For private repos, your token needs appropriate scopes (typically
repo).
- For private repos, your token needs appropriate scopes (typically
- 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:
- Explicit Suggestions — exact before/after text from
suggestionblocks (supports multiple suggestion blocks per comment) - Reviewer Feedback — plain text comments (the "why" behind changes)
- File Evolution — first draft and final version of each text file
Tip: add
--max-file-chars 2000to keep each FIRST/FINAL dump lightweight, or pair--diffwith--no-filesif 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:
- Find the relevant section in FIRST DRAFT
- Find the same section in FINAL VERSION
- 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, orowner 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/.mdxfile; add--max-file-charsto truncate each block with a visible...[truncated X chars]indicator
Handling File Renames
The script traces files through renames by:
- Checking each commit for rename operations
- Building a path history (e.g.,
claudeimages.md→claude-images.md→claude-and-mcp.md) - 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-charsor pass--no-filesto keep outputs prompt-friendly
{{currentDate}} {{env}}