review.md

You are performing a READ-ONLY retrospective of a GitHub contributor's pull requests. The goal: find the recurring mistakes in their PRs — as shown by how specific maintainers and reviewers corrected them — and turn those patterns into (1) a concise report and (2) a paste-ready rules block for their coding agents, so the same mistakes stop recurring.

Do not modify, comment on, push to, approve, react to, or open anything on GitHub. Only use gh read commands (gh search, gh pr view, gh api with GET). Write files only inside the current working directory.

Ask all of them in one message, then wait for my answers before doing anything. If I skip a question or say "defaults", use its default.

1. GitHub handle to analyze — no default, required: whose PRs are we reviewing?
2. Scope — default: every repository the handle has PRs in. Otherwise an org wildcard (e.g.--owner laravel orlaravel/* ) or an explicit repo list.
3. Mentors — whose corrections drive the lessons. Default: infer them yourself from the repos' owners and the people who most often merge or commit to this contributor's PRs. When in doubt, treat ANY maintainer edit, review, or change request as signal.
4. Time window — default: the last 12 months, computed from today.
5. Known concerns (optional) — anything you already suspect and want checked, or "none".

• Run gh auth status andgh api rate_limit . If auth is missing, stop and tell me.
• Cache every API response under ./data/ as JSON so reruns never re-fetch.
• Respect rate limits: if remaining calls < 100, sleep until the reset window.
• From here on, print a short progress update with counts at the end of every step.

For each state (merged, closed-unmerged, open), search PRs authored by the handle within the scope and window — `gh search prs --author <handle> --limit 1000` with `--json number,title,url,state,createdAt,closedAt,repository`, plus any owner/repo filters. Merge everything into `./data/prs.json`, dedupe by repo+number. Print counts per repo and per state.

For every PR fetch only: `/pulls/{n}/commits` (who authored each commit), `/pulls/{n}/reviews`, `/pulls/{n}/comments` (inline), `/issues/{n}/comments` (conversation), and `/issues/{n}/timeline` (title/description edits and closes). Flag a PR as "interesting" if ANY of these is true:

• a) a commit on the PR branch was authored or committed by a mentor (they fixed it themselves),
• b) a mentor left an inline comment, review, or conversation comment asking for or suggesting a change,
• c) any other human reviewer requested changes or suggested a specific change,
• d) the PR was closed unmerged and a maintainer left a reason,
• e) the PR title or description was edited by a maintainer.

Ignore bots (dependabot, github-actions, styleci, renovate, preview/deploy bots, etc.) and pure "thanks"/"LGTM" comments. Save ./data/interesting.json and print how many PRs qualified.

Skim each flagged PR's signals and drop false positives BEFORE spending deep-read effort on them:

• sync/dependency PRs whose branch merely carries pre-existing history,
• praise, excitement, or roadmap chatter not addressed to the author,
• bot noise of any kind,
• closes with zero comments and no stated reason,
• comments not directed at the author.

Record each drop with a one-line reason so the cut is auditable. Print how many flags survived triage.

For each surviving PR, read:

- the author's original diff (the commits they authored),

• every maintainer/reviewer commit's diff — what exactly they changed after the author,
• the review and inline comments, with the file and line each was attached to.

Record per PR: repo, PR URL, title, state, what the maintainer changed or asked for (keep sharp verbatim quotes), a one-line root cause, a primary category, optional extra categories, severity (major = shipped breakage, real-user impact, or the PR was closed/redone; minor = a real fix was needed; trivial = pure polish), who fixed it, and the evidence you saw.

Use these categories, adding new ones only if truly needed: scope creep / unrelated changes, naming, API design / public surface, backwards compatibility / breaking change, missing or weak tests, test style, docs / docblocks / comments, code style / formatting / lint, types / generics / PHPDoc / static analysis, over-engineering / unnecessary abstraction, wrong abstraction location, performance, edge cases, PR title/description quality, target branch / versioning, framework or project conventions, dependency / config choices, other.

• Rank categories by unique PR count (dedupe — a PR must not be double-counted within one category), noting which repos each pattern shows up in.
• For the top ~8 patterns: a one-sentence "what I keep doing", 2-3 example PR links, and the concrete rule that would have prevented each.
• Separately note: strengths (large features merged with zero corrections, repos with no flags), the repos where the contributor struggles — by rate AND by raw volume, flagging small samples inline — and a trend across the window (quarterly flag rate). Treat partial quarters as partial, and do NOT misread a low rate on recent PRs as improvement: feedback hasn't had time to accumulate.
• Be brutally honest and specific. No flattery, no padding. If a sample is small, say so in the same breath as the claim. Add a short method note covering: how many flags were excluded as false positives, that multi-category PRs exist, and any undercounting (e.g. squash merges hide maintainer fixes).

1. report.html — a single self-contained page, no external assets or scripts, clean scannable typography. Sections: summary numbers, top patterns ranked, per-pattern detail with PR links, strengths, "where I struggle", trend, and the list of major-severity items.
2. agent-instructions.md — a short paste-ready block for AGENTS.md / CLAUDE.md: imperative rules only, one line each, grouped by category, every rule backed by the data (cite the example PRs), ending with a "Before opening a PR" checklist of at most 10 items.
3. Keep ./data/ as the raw cached JSON so the analysis can be rerun or audited.

• Render the HTML report and inspect it at both desktop and phone widths; fix any overflow, broken markup, or illegible text before delivering.

• Spot-check every quoted maintainer line and linked PR against the cached data.

• In your final reply: headline numbers, the top patterns with example PR links, strengths, struggle repos, the trend verdict, and links to all three deliverables.

• Read-only on GitHub, always. Never post, edit, push, approve, or react.

• Show counts after each step; stop to ask only if something genuinely blocks you.

• If a step finds far more PRs than expected, say so and keep going — never silently truncate.