zsxh1990/pr-genius

type: Knowledge Bundle title: PR Genius — the board for the PRs you sent out description: Project management for your outbound open-source contributions — not a code reviewer. Know which of your open PRs needs you today, and what to do about it. version: 2.2.3 created: 2026-07-01 updated: 2026-10-17 author: zsxh1990 conforms_to: OKF v0.1 (Sudhakaran88/okf-conformance) + agent_guidelines extension

mcp-name: io.github.zsxh1990/pr-genius

PR Genius

Somewhere in your GitHub there are PRs you have stopped opening.

One needs a rebase you keep meaning to do. One has been red for four days and

nobody told you. Three have sat untouched for three weeks. And one you avoid

entirely, because opening it would mean confirming that it is dead.

PR Genius is the board for that work — the contributions you sent out into other people's repositories, where you have no tracker, no standup, and no clue.

It is not a code reviewer. By default it never reads your diff, and it will never tell you your code is correct. There are good tools for that, and this is not one of them.

It answers the question a working contributor actually has on a Tuesday morning: of everything I have sent out, what do I touch today — and what exactly do I do about it?

Why this exists

GitHub remembers the PR.

It does not remember why you closed your third attempt on a given repo. What worked. What didn't. Which reviewer actually answers and which commented once and vanished. Whether the thing that got you bounced last time was the size, the missing issue link, or the tone.

That knowledge lives in your head. It dies when the session ends.

PR Genius is where it goes instead.

A Repo Profile captures the what a project wants.

A case study captures the how a contribution landed or died.

Your own status history captures the then-what — how long it waited, what

changed, whether it ever came back.

Neither a code reviewer nor a chat model can have the third one. They see your PR once, in someone else's repo. This sees your portfolio over months.

What it knows

It knows · Why it matters to you How 67 large projects actually behave — merge rates, review cadence, what gets closed · You stop guessing what encode/httpx wants and start matching it Why real PRs got rejected — written down, with the evidence · You stop repeating the mistake that already cost someone else three weeks What your own PRs did over time — which state each sat in, for how long · You find out a PR died *while it was dying*, not three weeks later The policy of the repo you are aiming at · A Fixes #N in the body is still the single most common reason a first PR gets bounced

Numbers, for the sceptical: 753 loaded patterns, 190 harvested failed-PR observations, 68 repo profiles, 302 reviewed cases. Those are receipts for the sentence above, not the point of it — every one of them is verified against the live tree on each release by scripts/verify_claims.py.

One of those corpora deserves a caveat: success-patterns/ is retrieval/reference only and is not wired into scoring. It is browsable context, not a positive-feedback system, and no verdict has ever been changed by it. The 61 anti-patterns are what actually move the risk tier.

The nine states are nine decisions

A number on a dashboard tells you something is wrong. A *state* tells you what to do about it.

State · What it means for you today NEEDS_REBASE · Twenty minutes of work and this PR is still alive. CI_FAILING · It has been red for days and nobody was going to tell you. STALE_REVIEW · Someone looked and stopped. Move now or it goes cold. STALE_NO_REVIEW · Nobody looked. Wait, ping, or walk away — but decide. CLEAN · Leave it alone. That is also a decision worth being told. WAITING · Still inside a normal response window. Go do something else.

Half the value of a board is being told what not to spend today on.

The two moments it shows up for

Before you open something. Is this ready, or am I about to waste a maintainer's attention?

python3 -m prgenius coach "fix: timeout in connection pool" \
  --repo encode/httpx --body "Fixes #4821"

Five answers, each with a next move — READY_TO_SUBMIT, FIX_BEFORE_SUBMIT, NEEDS_DISCUSSION, IMPROVE_CHANCE, ASK_MAINTAINER. It is read-only and advisory: it never comments, labels, closes or merges anything.

After it is out there. Which of these needs me?

python3 -m prgenius status --author your-handle

Nine states, stale detection, and a suggestion per PR — fix CI, rebase, ping, wait, or abandon. Run it from cron and it becomes the daily line you actually read.

Install

pip install "prgenius-core[mcp]"     # engine + MCP server

What the wheel actually ships. Since #116, prgenius-core bundles the

decision-relevant corpus — anti-patterns/, profiles/, pr-observations/,

docs/policies/, locale/ — as prgenius/data/, and root resolution finds it

without a checkout. A clone and PRGENIUS_REPO_ROOT are overrides, not

prerequisites.

success-patterns/ (~2.7 MB) is deliberately not bundled: the scorer never

consults it (#69), so it would triple the wheel without changing a decision.

doctor reports success_patterns_installed: false rather than pretending.

```bash

prgenius-core doctor # where the knowledge came from, what it found, what it did not

`

doctor is the first thing worth running. It reports repo_root_source and the

per-corpus counts on its first lines, and it never lies about what is missing.

python3 -m prgenius analyze "feat: add feature" --repo org/repo --body "Fixes #123"
python3 -m prgenius status --author your-handle
python3 -m prgenius profile get owner/name     # what does this project actually want?

CLI reference

Console script is prgenius-core; python3 -m prgenius is equivalent. Every command takes --repo-root to point at a knowledge-base checkout.

Command · What it does · Key flags status · Health of your in-flight outbound PRs · --author, --format json, --save-snapshot coach · Ready to open? — exit 0 = pass, 1 = fail · title, --repo, --body contributor · Contributor decision (5 actions) · title, --repo, --diff-stat maintainer · The maintainer's side of the same call (5 actions) · title, --repo analyze · PR analysis + improvement suggestions · title, --repo, --body, --diff-stat triage · Policy-aware preflight checks · title, --repo, --diff-stat profile get · Show a repo profile · owner/repo profile writeback · Profile update suggestions (dry-run) · --author auto-ping · Suggest pings for stale PRs (dry-run; --confirm acts) · --author, --confirm auto-rebase · Suggest rebases (dry-run; --confirm acts) · --author, --confirm harvest · A rejected PR → an anti-pattern draft · owner/repo [number] doctor · Install / knowledge-base / gh / MCP self-test · --format json issue / issue-batch · Score one issue, or a labelled batch · --repo, --number, --state, --limit, --format review-queue · Prioritised review-queue digest · --prs-file mcp serve · MCP server on stdio · — eval / suggest · Older aliases, kept for compatibility · —

Where it runs

From your shell — what is above.

From cron, as the one line you read with coffee:

# scripts/pr_status_heartbeat.sh --all
0 10 * * * cd /path/to/pr-genius && bash scripts/pr_status_heartbeat.sh --all

As an MCP server, so your coding agent can read your contribution history instead of starting from zero every time. 14 tools — status_prs, contributor_view, maintainer_view, get_repo_profile, search_patterns and the rest. See MCP Configuration.

As a GitHub Action on a repository you maintain — advisory comments on incoming PRs, never blocking. See GitHub Action.

As a DSH (Cordis) plugin, so the board lives next to the chat you are already in: sidebar action, session tab, right-hand panel, settings, and /prgenius. See DSH Plugin.

What it will never do

Stated plainly, because the rest of this page is worthless if these are fuzzy:

• It will not tell you your code is correct. It does not judge your logic.

You can hand it a diff (--diff) and it will flag install commands, downloads piped into a shell, and secret-shaped strings — a keyword pass, not a review. Without one, it looks at the summary counts only.

• It will not write or send anything on your behalf unless you pass an

explicit --confirm. Every mutating command is dry-run by default.

• It will not phone home. Analysis is local: no LLM, no API key, no network

call. The commands that touch GitHub do it with *your* token and only for PR metadata. There is no telemetry — see docs/ADOPTION_DATA.md for what is measured instead and why we chose not to build the rest.

• It will not pretend. If a fact is not verified, the docs say so. This

page has been wrong before and the corrections are in the changelog.

🤖 GitHub Action

Advisory analysis on incoming PRs to a repository you maintain. It never blocks a merge and never fails a job — every path degrades to a warning.

name: PR Genius
on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  issues: write   # required when comment_mode != never (post/update PR comment)

jobs:
  pr-genius:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: zsxh1990/pr-genius@v2.1.4
        id: pr-genius
        with:
          title: ${{ github.event.pull_request.title }}
          repo: ${{ github.repository }}
          body: ${{ github.event.pull_request.body }}
          pr_number: ${{ github.event.pull_request.number }}
          comment_mode: always   # never | high_risk | always

comment_mode controls *whether* the analysis is posted as a PR comment: never (default), high_risk, or always (existing comments are updated in place — no spam). comment_on_high_risk: true still works as an alias.

comment_format controls *how long* that comment is:

• compact — default. A short bullet list: risk tier, finding counts, the

one-line summary, and a link to the action run. Around 6 lines.

• verbose — the full table: every signal, the whole anti-patterns table, the

full checklist. Can exceed 100 lines.