pr-walkthrough

name	pr-walkthrough
description	Generate an evidence-grounded markdown walkthrough for a pull request.
allowed-tools	Bash(echo *), Bash(rp1 *), Bash(git *), Bash(gh *)
metadata	{"category":"review","is_workflow":true,"workflow":{"run_policy":"fresh","identity_args":[]},"version":"1.0.0","tags":["pr","review","walkthrough","markdown"],"created":"2026-04-26T00:00:00.000Z","updated":"2026-04-26T00:00:00.000Z","author":"cloud-on-prem/rp1","arguments":[{"name":"TARGET","type":"string","required":false,"description":"PR number, PR URL, branch name, or empty for the current branch"},{"name":"BASE_BRANCH","type":"string","required":false,"default":"main","description":"Diff base branch used when no remote PR is available"}],"sub_agents":["rp1-dev:pr-walkthrough-reporter"]}

PR Walkthrough

Generate a slide-ready markdown walkthrough from direct pull request evidence. The output is a reviewer-orientation artifact with plain markdown fallback, not a review verdict or rendered slide reader.

Use the pre-resolved projectRoot, kbRoot, workRoot, and codeRoot values from the generated Workflow Bootstrap section. Run all source-control commands from codeRoot, and write generated artifacts only under workRoot.

Do not read .rp1/work/pr-reviews/ or any existing pr-review artifacts as source material. The walkthrough source of truth is the target PR metadata, changed files, diffs, and commit summaries gathered in this workflow.

STATE-MACHINE

stateDiagram-v2
    [*] --> collecting
    collecting --> publishing : evidence_ready
    publishing --> [*] : done

On each phase transition, report via:

rp1 agent-tools emit \
  --workflow pr-walkthrough \
  --type status_change \
  --run-id {RUN_ID} \
  --step {CURRENT_STATE} \
  --data '{"status": "running"}'

• RUN_ID comes from the generated Workflow Bootstrap section.
• Derive RUN_NAME from the resolved target: use "PR Walkthrough: PR #{number}" when a PR number is available, otherwise "PR Walkthrough: {branch_name}".
• On the first emit only, include --name "{RUN_NAME}".

Example sequence:

rp1 agent-tools emit --workflow pr-walkthrough --type status_change --run-id {RUN_ID} --name "PR Walkthrough: PR #42" --step collecting --data '{"status": "running"}'
rp1 agent-tools emit --workflow pr-walkthrough --type status_change --run-id {RUN_ID} --step publishing --data '{"status": "running"}'
rp1 agent-tools emit --workflow pr-walkthrough --type status_change --run-id {RUN_ID} --step publishing --data '{"status": "completed"}'

On a blocking error, emit the current step with {"status":"failed","reason":"..."} and stop without dispatching the reporter or registering an artifact.

1. Collect Direct Evidence

Execute immediately. Do not ask for clarification. Fail clearly during collecting when the target cannot identify one PR or one local diff.

Emit collecting running before command execution.

1.1 Resolve Target

Normalize inputs:

Input	Resolution
Empty TARGET	Use the PR associated with the current branch via gh pr view; if none exists, use git diff BASE_BRANCH...current_branch
Numeric target	Use gh pr view {TARGET} and gh pr diff {TARGET}
PR URL	Use gh pr view {TARGET} and gh pr diff {TARGET}
Branch name	Use gh pr view {TARGET} if available; otherwise use git diff BASE_BRANCH...{TARGET}

Implementation guidance:

1. Set target from {TARGET} and base_branch from {BASE_BRANCH}.
2. Get current_branch with git -C {codeRoot} branch --show-current.
3. Classify a numeric target with ^[0-9]+$.
4. Classify a PR URL when the target contains /pull/.
5. For empty target or branch target, first try gh pr view from {codeRoot}. If that fails, validate that both base and head refs exist locally before using the git-only fallback.

If no PR exists and the local fallback cannot produce a diff, fail with a message that includes the attempted target and base branch.

1.2 Gather Evidence

For a resolved GitHub PR target, collect:

gh pr view {resolved_pr_target} \
  --json number,title,body,url,author,baseRefName,headRefName,headRefOid,baseRefOid,additions,deletions,changedFiles,files,commits
gh pr diff {resolved_pr_target} --name-only
gh pr diff {resolved_pr_target} --patch

For a git-only target, collect:

git -C {codeRoot} diff --name-only {base_branch}...{head_ref}
git -C {codeRoot} diff --patch {base_branch}...{head_ref}
git -C {codeRoot} diff --stat {base_branch}...{head_ref}
git -C {codeRoot} log --oneline --no-decorate {base_branch}..{head_ref}

For PR targets, attempt a local stat with git -C {codeRoot} diff --stat {baseRefName}...{headRefName} when refs exist. If local refs are unavailable, use PR JSON additions, deletions, and changedFiles as the stats source.

Required failure behavior:

• If gh is unavailable for a numeric or URL target, fail during collecting; do not silently switch to an unrelated local diff.
• If a branch target has no PR and no local diff against BASE_BRANCH, fail during collecting.
• If the collected changed-file list and patch are both empty, fail during collecting.

1.3 Build Evidence JSON

Build one EVIDENCE_JSON object from direct evidence only:

{
  "source": "github_pr | git_diff",
  "target": "{TARGET}",
  "base_branch": "{base_branch}",
  "head_ref": "{head_ref}",
  "review_id": "{review_id}",
  "pr": {},
  "file_names": [],
  "patch": "",
  "stats": "",
  "commit_summaries": [],
  "evidence_index": []
}

Assign evidence IDs before dispatch:

ID Pattern	Source
E-PR-001	PR metadata, title, body, URL, author, base/head refs, or git-only branch metadata
E-FILE-###	Changed-file entries from gh pr diff --name-only, PR JSON files, or git diff --name-only
E-DIFF-###	Meaningful diff hunks or patch excerpts selected for walkthrough grounding
E-COMMIT-###	Commit summaries from PR JSON commits or git log

Keep patch data concise enough for the reporter to process, but preserve the file path and hunk headers for every included diff excerpt. The evidence index entries must include id, kind, source, and summary.

Derive review_id as pr-{number} for PR targets. For branch-only targets, sanitize the head ref by lowercasing and replacing characters outside [a-z0-9._-] with -.

2. Generate Walkthrough

After evidence collection succeeds, emit publishing running and dispatch the reporter:

{% dispatch_agent "rp1-dev:pr-walkthrough-reporter" %} Generate an evidence-grounded slide-ready markdown PR walkthrough with plain markdown fallback. EVIDENCE_JSON: {{stringify(EVIDENCE_JSON)}} KB_ROOT: {kbRoot} WORK_ROOT: {workRoot} CODE_ROOT: {codeRoot} REVIEW_ID: {{review_id}} Return single-line JSON with path. {% enddispatch_agent %}

Wait for completion. Parse the reporter output as single-line JSON:

{"path":"pr-walkthroughs/{REVIEW_ID}-walkthrough-{NNN}.md"}

If the reporter fails or the output cannot be parsed, emit publishing with {"status":"failed","reason":"reporter failed"} and stop.

Validate the returned path before registration:

• It must be relative.
• It must start with pr-walkthroughs/.
• It must end with .md.
• It must not contain ...

Do not reject an otherwise valid reporter artifact because it contains the canonical slide-ready markdown contract fields, reserved <!-- rp1-slide: ... --> markers, slide metadata blocks, or <!-- rp1-notes --> speaker-note sections.

3. Register Artifact

Register the reporter output during publishing:

rp1 agent-tools emit \
  --workflow pr-walkthrough \
  --type artifact_registered \
  --run-id {RUN_ID} \
  --step publishing \
  --data '{"path": "{ARTIFACT_RELATIVE_PATH}", "feature": "{review_id}", "storageRoot": "work_dir", "format": "markdown"}'

Then emit publishing completed:

rp1 agent-tools emit \
  --workflow pr-walkthrough \
  --type status_change \
  --run-id {RUN_ID} \
  --step publishing \
  --data '{"status": "completed"}'

Output

Output only:

## PR Walkthrough Complete

**Target**: {target_description}
**Artifact**: {ARTIFACT_RELATIVE_PATH}
**Evidence**: {changed_file_count} files, {commit_count} commits

{% include_shared "anti-loop.md" %}

File-specific constraints:

• Do not read existing pr-review artifacts
• Do not dispatch the reporter more than once
• Do not register more than one artifact
• Do not strip or forbid the canonical slide-ready markdown contract metadata, reserved slide markers, slide metadata blocks, or speaker notes
• Do not produce a rendered slide reader, alternate artifact path, extra artifact, or review verdict