explain-this-pr

Explain This PR

Read a GitHub pull request, understand what it changes, and write a plain-English explanation. Post it as a PR comment so reviewers have instant context.

---

Step 1: Check Setup

Confirm gh is authenticated:

gh auth status

If not authenticated: gh auth login and follow the prompts.

Confirm input. The user must provide one of:

• A GitHub PR URL (e.g. https://github.com/owner/repo/pull/123)
• A PR number in the current repo (e.g. #123)
• The keyword "current" to use the PR for the current branch

If no input, ask: "Which PR should I explain? Share the URL, PR number, or say 'current' for the active branch."

---

Step 2: Fetch PR Context

Get PR metadata:

gh pr view PR_URL_OR_NUMBER --json number,url,title,body,author,baseRefName,headRefName,additions,deletions,changedFiles,commits,labels,state,isDraft

If isDraft is true, note this to the user: "This PR is still in draft. The explanation is based on its current state."

Get the diff:

gh pr diff PR_URL_OR_NUMBER

If the diff is over 400 lines, read the --stat summary and the first 200 lines of the diff:

gh pr view PR_URL_OR_NUMBER --json files
gh pr diff PR_URL_OR_NUMBER | head -200

Get existing comments (to avoid repeating what is already there):

gh pr view PR_URL_OR_NUMBER --json comments --jq '.comments[].body' 2>/dev/null | head -20

---

Step 3: Write the Explanation

Write two paragraphs. Read each rule before writing.

Paragraph 1: What it does (technical)

• One sentence per major change
• Name the specific files, functions, or systems that changed
• State the before/after if the diff makes it clear
• Include concrete numbers if present in the diff (lines removed, tables dropped, endpoints added)
• Active voice, present tense

Example:

Replaces the in-memory session cache in auth.middleware.ts with a Redis-backed cache (src/cache/redis.ts). Adds get, set, and invalidate methods to the new Redis module and wraps UserService.getById() with a 5-minute TTL. Removes the Map-based cache that was limited to a single process and caused session drift across multiple instances.