learn-from-prs

name	learn-from-prs
description	Extract patterns from human PR review comments. Shows proposals with citations for users to decide which become AGENTS.md rules. Filters bot noise and provides clickable PR links.

Learn From PRs

Extract patterns from human PR review comments. Shows proposals with citations for you to decide which become AGENTS.md rules.

When to Use

• Setting up AGENTS.md for a new project
• Onboarding new team members
• Documenting implicit team conventions
• "What patterns does this team follow?"
• "What do reviewers keep asking for?"

Critical Rules

1. AGENTS.MD IS FOR AI AGENTS - Rules must be things an AI can follow when writing code
2. SKIP HUMAN PROCESS PATTERNS - These are NOT for AGENTS.md:
   • "keep PRs focused" ❌ (PR workflow, not code)
   • "validate with product specs" ❌ (AI can't consult humans)
   • "add PR description" ❌ (PR workflow)
   • "add tests" ❌ (too generic)
   • "remove comments" ❌ (too generic)
3. FOCUS ON CODE PATTERNS - Things AI can actually do:
   • Specific APIs: "use X instead of Y" ✅
   • Specific architecture: "put logic in A, not B" ✅
   • Specific utils: "use utilX from path/to/utils" ✅
   • Specific style: "use arrow functions for components" ✅
   • Specific organization: "shared types in shared folders" ✅
4. 3+ OCCURRENCES - Threshold for team-specific patterns
5. AUTO-ESCALATE - If < 3 patterns, fetch more PRs. Don't ask user.
6. OUTPUT DIRECTLY - Don't ask "which patterns to add?" - just output the AGENTS.md rules.

Parameters

Param	Default	Description
author	(all)	GitHub username whose PRs to analyze. If omitted, analyzes all PRs
repo	(current)	Repository owner/repo
limit	50	Starting PR limit. Increase if not enough patterns found

Workflow

Run Analysis

node scripts/analyze-prs.js <owner/repo> [--limit <n>] [--skip <n>] [--author <username>]

Auto-Escalation with Pagination

DO NOT re-fetch PRs you already have. Use --skip for pagination:

1. First run: --limit 50 → analyze, keep comments in memory
2. If < 3 patterns → --limit 50 --skip 50 → append new comments
3. If still < 3 → --limit 100 --skip 100 → append
4. If still < 3 → --limit 200 --skip 200 → append
5. If still < 3 → --limit 500 --skip 500 → append
6. After 1000 total PRs, report findings

Accumulate comments across runs. Don't discard previous results.

Your Job: Semantic Pattern Finding

The script outputs a flat list of all human review comments. YOU (Claude) must find semantic patterns.

What the script does:

• Fetches PR review comments
• Filters out bots
• Outputs flat JSON list with: body, reviewer, url, pr

What YOU must do:

1. Read ALL comments
2. Find semantic patterns - comments that mean the same thing but use different words
3. SKIP GENERIC PATTERNS - these are useless nitpicks everyone knows:
   • "add tests" ❌
   • "remove comments" ❌
   • "add PR description" ❌
   • "keep PRs focused" ❌
   • "remove redundant code" ❌
   • "justify your changes" ❌
4. FOCUS ON TEAM-SPECIFIC patterns - things unique to THIS codebase:
   • Specific APIs: "use X instead of Y" ✅
   • Specific utils: "use utilX from path/to/utils" ✅
   • Specific architecture: "put logic in A, not B" ✅
   • Specific imports: "import X from specific/path" ✅
   • Specific style: "arrow functions for components" ✅
5. For team-specific patterns, threshold is 3+ occurrences (not 5)
6. Group semantically similar comments and count occurrences

Output Rules

Output AGENTS.md rules directly. Don't ask user to choose.

Format:

## AGENTS.md Rules (from PR review patterns)

### [Category]
- Rule 1 (cite: [PR](url))
- Rule 2 (cite: [PR](url))

Example output:

## AGENTS.md Rules (from PR review patterns)

### API Usage
- Use `newApi()` instead of `legacyApi()` - legacy is deprecated (cite: [PR](url))

### Architecture
- Put feature flags in controllers, NOT services - service flags cause cache issues (cite: [PR](url))
- Use `checkFeature` from `src/utils/features.ts` (cite: [PR](url))

### Components
- Use arrow function syntax: `const Component = (props: Props) => { ... }` (cite: [PR](url))
- Shared types go in `types/` folder, not duplicated per component (cite: [PR](url))

If no code patterns found: "No actionable code patterns found. Team feedback is situational."

Error Handling

Error	Response
gh not authenticated	Run gh auth login first
No PRs found	Check repo name or try without author filter
< 3 patterns found	Auto-escalate to next PR limit (do not ask user)
No patterns after 1000 PRs	Report "no strong patterns found" with observed themes

Requirements

• gh CLI authenticated
• Node.js 18+