@gsimone/pr-health

PR Health

Tells you which of your open pull requests are actually stuck, and stays quiet otherwise.

Intent

Open PRs go quiet for boring, fixable reasons — CI went red, the branch picked up conflicts, a review bot left comments nobody answered. GitHub notifies on all of it equally, so none of it registers. This package exists to answer one question: which of my PRs need a hand right now?

Success looks like a short email on the mornings something actually broke, and no email at all on the mornings nothing did.

What counts as stuck

A PR is reported when it has at least one concrete, fixable problem:

Deliberately not reported:

• Drafts. Stuck on purpose.
• Abandoned PRs (idle 120+ days). Parked, not broken.
• Idleness by itself. There is no "stale" rule. Tested against a real account, a 3-day idle threshold flagged 30 of 34 open PRs — a wall of noise that hides the six that were genuinely red.

Prerequisites

A fine-grained GitHub PAT saved as the secret githubPat, with api.github.com approved as a host, and read access to Pull requests, Contents, Checks, Commit statuses, and Issues.

Some organizations reject fine-grained PATs whose lifetime exceeds 366 days, or require SAML. Those PRs are skipped and counted in accessWarning rather than failing the run.

Setup

1. Save the PAT at /account/secrets/new?name=githubPat&allowedHosts=api.github.com.
2. Run the check once on demand (see AGENTS.md) to confirm it reads your PRs.
3. Enable the daily-check job when you want the morning email.

Done when

checkPrHealth() returns your genuinely-stuck PRs and an empty digest on a clean day, and the job emails you only when the set changes.