Repo PR Triage
Scanned@patrob
npx machina-cli add skill @patrob/repo-pr-triage --openclawPR Triage
Score and prioritize GitHub PRs against a project's vision document. Three-step workflow: onboard, scan, report.
Quick Start
# 1. Onboard: gather repo context, interview the owner
python3 scripts/onboard.py https://github.com/owner/repo --output-dir ./triage-config
# 2. Scan: score open PRs against the vision
python3 scripts/scan.py https://github.com/owner/repo ./triage-config/vision.md --output scores.json
# 3. Report: generate markdown triage reports
python3 scripts/report.py scores.json --output-dir ./triage-reports
Workflow
Step 1: Onboard (one-time per repo)
Run scripts/onboard.py with a GitHub repo URL. It fetches the README, CONTRIBUTING.md, recent releases, and repo metadata via gh CLI, then outputs an interview prompt.
Use the interview prompt to ask the repo owner these questions:
Identity & Mission:
- In one sentence, what is this project and who is it for?
- What problem does it solve that alternatives do not?
- What are your 3-5 non-negotiable principles?
Priorities: 4. Rank contribution areas by importance: security, bugs, features, performance, docs, tests, refactoring 5. What types of PRs would you auto-reject? 6. What types of PRs would you fast-track?
Red/Green Flags: 7. What patterns signal low-quality contributions? 8. What makes you excited to review a PR? 9. Specific areas where you want help?
Context: 10. Growth mode, maintenance mode, or transitioning? 11. Upcoming milestones affecting prioritization? 12. How do you handle breaking changes?
After the interview, generate two files in the output directory:
vision.md- Project mission, identity, priorities, alignment signalsrubric.md- Scoring rubric customized fromreferences/rubric-template.md
Step 2: Scan (run per triage session)
Run scripts/scan.py with the repo URL and vision doc path. It:
- Fetches open PRs via
gh pr list(title, body, labels, stats, author, date) - Applies rule-based scoring: base 50, with positive/negative modifiers
- Detects potential duplicates via title similarity
- Outputs JSON with scores, reasoning, and distribution
The scan uses heuristic scoring (keyword matching, diff size, test mentions). For deeper analysis, read the JSON output and apply additional LLM reasoning to ambiguous PRs (scores 40-60).
Options:
--count N- Number of PRs to fetch (default: 100)--output file.json- Save to file instead of stdout
Step 3: Report (run after scan)
Run scripts/report.py with the scan JSON. It generates four markdown files:
prioritize.md- PRs scoring 80+ (fast-track for review)review.md- PRs scoring 50-79 (standard queue)close.md- PRs scoring below 50 (likely close or request changes)summary.md- Distribution, top 3, patterns, duplicates, active authors
Scoring Overview
Base score: 50. Key modifiers:
| Signal | Points |
|---|---|
| Security fix | +20 |
| Bug fix with tests | +10 |
| Core functionality improvement | +10 |
| Performance (measured) | +8 |
| Small focused diff | +5 |
| Has tests | +5 |
| Spam/promotion | -30 |
| Unwanted dependency | -25 |
| Large diff, no tests | -15 |
| No description | -5 |
Full rubric: references/rubric-template.md
Example vision doc: references/example-vision.md
Recurring Triage via Cron
Set up a cron job to scan weekly:
description: Weekly PR triage for owner/repo
schedule: "0 9 * * MON"
model: anthropic/claude-sonnet-4-20250514
channel: telegram
Cron prompt: "Run pr-triage scan on https://github.com/owner/repo using ./triage-config/vision.md, generate reports, and send the summary."
Requirements
ghCLI installed and authenticated (gh auth login)- Python 3.10+
- No additional Python packages needed (stdlib only)
Overview
PR Triage scores GitHub PRs and issues against a project's vision document. It follows a three-step workflow—onboard, scan, and report—and leverages a vision-based rubric to prioritize, review, de-duplicate, or batch-process open PRs via the gh CLI. This approach helps teams align contributions with mission and scale triage across repositories.
How This Skill Works
During onboarding, you generate vision.md and a scoring rubric by interviewing the repo owner. The scan step fetches open PRs via gh pr list, applies rule-based modifiers to a base score, detects potential duplicates with title similarity, and outputs a JSON file with scores and reasoning. The report step consumes the scores to create four markdown files (prioritize.md, review.md, close.md, summary.md) for actionable triage.
When to Use It
- When you need to prioritize PRs that best align with the project vision before reviews.
- When you suspect multiple similar PRs and want to identify duplicates quickly.
- When you want to batch-process open PRs to streamline triage workload.
- When onboarding a new repository and building a vision doc to guide contributions.
- When setting up a recurring weekly triage cadence using a cron-like schedule.
Quick Start
- Step 1: Onboard: python3 scripts/onboard.py https://github.com/owner/repo --output-dir ./triage-config
- Step 2: Scan: python3 scripts/scan.py https://github.com/owner/repo ./triage-config/vision.md --output scores.json
- Step 3: Report: python3 scripts/report.py scores.json --output-dir ./triage-reports
Best Practices
- Define and maintain a clear vision.md aligned with mission, identity, and priorities.
- Onboard each repo once to bootstrap the vision and scoring rubric.
- Run scans regularly and use the four generated reports to guide triage decisions.
- Use the duplicate detection to reduce noise from overlapping PRs.
- Refine rubric thresholds over time as the project evolves and PR patterns change.
Example Use Cases
- Onboard a repository to generate vision.md and rubric.md from an owner interview.
- Scan open PRs to produce scores.json with reasoning for each PR.
- Generate triage reports: prioritize.md, review.md, close.md, and summary.md.
- Schedule weekly triage via cron to keep the backlog manageable.
- Leverage gh CLI to fetch PR data and feed the triage pipeline.
