Skip to content

pr-walkthrough

Generate a markdown walkthrough that helps reviewers understand what changed in a pull request before they read the full diff.

pr-walkthrough is an orientation tool. It does not approve, reject, or comment on a pull request. Use pr-review when you need a verdict and actionable findings.

Synopsis

/pr-walkthrough [target] [base-branch]

/rp1-dev-pr-walkthrough [target] [base-branch]

$rp1-dev-pr-walkthrough [target] [base-branch]

When To Use It

Use pr-walkthrough when... Prefer another command when...
The PR is large enough that reviewers need a map. You need a merge-readiness verdict; use pr-review.
You want a narrative summary grounded in PR evidence. You only need diagrams; use pr-visual.
You want to share reviewer focus areas before human review starts. Human comments already need fixes; use address-pr-feedback.

Parameters

Parameter Position Required Default Description
TARGET $1 No Current branch PR number, PR URL, branch name, or empty for the current branch
BASE_BRANCH $2 No main Diff base branch used when no remote PR is available

Input Resolution

Input Type Example Resolution
Empty - Uses the PR associated with the current branch, falling back to a local diff against BASE_BRANCH
PR number 123 Fetches PR metadata and diff with gh
PR URL https://github.com/owner/repo/pull/123 Fetches PR metadata and diff with gh
Branch name feature/auth Uses the branch PR when available, otherwise uses a local diff against BASE_BRANCH

If the target cannot identify exactly one PR or one local diff, the workflow fails during evidence collection instead of producing an unrelated artifact.

Workflow

stateDiagram-v2
    [*] --> collecting
    collecting --> publishing : evidence ready
    publishing --> [*] : walkthrough written
Step What Happens
collecting Resolves the target and gathers PR metadata, changed files, diff excerpts, and commits.
publishing Writes the walkthrough and registers it with the run so it can be opened from Arcade.

Reading The Walkthrough

The walkthrough is designed to answer:

Question Where to look
What is the PR trying to accomplish? At-a-glance summary
Which files or areas changed? Change map
What should reviewers inspect first? Reviewer focus areas
What risks or open questions remain? Risks and questions
Which source evidence supports the claims? Evidence index

Use the walkthrough before or alongside human review. It is especially useful when a PR spans multiple folders, introduces a new flow, or needs a short written explanation for reviewers who were not involved in the implementation.

Output

The workflow writes a markdown artifact under .rp1/work/pr-walkthroughs/ and registers it with the run. Open it from command output, the file path, or Arcade.

Expected contents:

  • PR purpose and size at a glance
  • Evidence index with source references
  • Reviewable change map
  • Narrative walkthrough of major changes
  • Reviewer focus areas
  • Risks and questions grounded in evidence

Arcade may offer a slide-style reading mode for supported walkthroughs. Markdown viewing is always available, and it is the best fallback when you want to copy, quote, annotate, or search the walkthrough text.

Examples

Walk Through Current Branch

/pr-walkthrough

/rp1-dev-pr-walkthrough

$rp1-dev-pr-walkthrough

Walk Through Specific PR

/pr-walkthrough 123

/rp1-dev-pr-walkthrough 123

$rp1-dev-pr-walkthrough 123

Example final output:

PR Walkthrough Complete

Target: PR #123
Artifact: pr-walkthroughs/pr-123-walkthrough-001.md
Evidence: 8 files, 3 commits

See Also