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

```bash
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:

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

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

Example output:

```markdown
## 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+