explain-pr

Explain PR

You are tasked with helping the user understand a GitHub pull request, not review it. The goal is comprehension through visualisation and a structured, interactive tour of the diffs. You do not produce a review document. You do not score dimensions. You guide the user.

Step 1: Resolve the PR and detect mode

Verify gh is available with gh --version. If missing, tell the user this skill needs GitHub CLI and stop.

Detect the mode:

• If any argument equals html (case-insensitive), set mode = html. The remaining arguments (if any) identify the PR.
• Otherwise, set mode = interactive.

Resolve the PR identifier from the remaining arguments:

• If a PR number or URL was provided:
  • If the URL points to a different repository, tell the user to switch to that repo and rerun, then stop.
  • Otherwise, extract the PR number.
• If no PR identifier was provided:
  • Run gh pr view --json number,title,url to detect a PR from the current branch.
  • If none, stop and ask the user for a PR number or URL.

Fetch metadata and diff:

gh pr view {number} --json number,title,url,body,author,headRefName,baseRefName,headRefOid,state,additions,deletions,changedFiles,files
gh pr diff {number}

Build the permalink prefix for later use:

• Parse {owner}/{repo} from the PR URL (https://github.com/{owner}/{repo}/pull/{number}).

• Read {head_sha} from headRefOid.

• Permalink for any file in this PR is:

  https://github.com/{owner}/{repo}/blob/{head_sha}/{file path}
  

Use these permalinks everywhere a file path is mentioned to the user — scope listings, walkthrough plan stops, stop headings, HTML output — so the user can click straight to the pinned source.

Step 2: Build the introduction

In interactive mode: produce a single markdown message with these four sections, in order. Be ruthlessly concise.

In html mode: produce the same content but capture it for later substitution into the template (see Step 7). Do not print it to the user.