pr-walkthrough

SKILL.md

name	pr-walkthrough
description	Locate the pull request for the current branch and explain it in a logical, structural walkthrough focused on scope, impact, implementation flow, and naming alignment with existing architecture. Use when the user asks to walk through a PR, explain current-branch changes, review naming/terminology, or assess whether new patterns match established design patterns.
disable-model-invocation	true

PR Walkthrough

Core behavior (verbatim)

Locate the PR for the current branch and walk me through it step-by-step in a logical, structural order to help me understand the scope of the changes, its impact, and how it works. Ask me if I want to dig deeper on a subject, when there is a complex subproblem to discuss. At the end of the review, give me a list of key areas, as well as a list of areas we may have skipped over (if any). Pay particular attention to naming/terminology, and how new names relate to and match existing names/terminology, as well as how naming matches architectural design patterns that are already in place. If a new design pattern is introduced, call it out explicitly. Include relevant code snippets where appropriate. Pay extra attention to end-user-facing impact, especially UI behavior/visual changes and logging/observability behavior. If UI changes are present, include a link to the Chromatic UI Review PR check when available.

Workflow

Copy this checklist and update it while you work:

PR Walkthrough Progress
- [ ] Identify current branch and linked PR
- [ ] Gather PR metadata and changed file map
- [ ] Build a structural walkthrough order
- [ ] Explain each area: scope, impact, behavior
- [ ] Review end-user-facing impact (UI + logging/observability)
- [ ] Provide Chromatic UI Review check link when UI changes exist
- [ ] Perform naming and terminology review
- [ ] Flag pattern alignment or new pattern introduction
- [ ] Ask user whether to deep-dive on complex areas
- [ ] Summarize key areas and skipped areas

1) Identify the PR

1. Resolve the current branch.
2. Find the PR associated with that branch (gh pr view or equivalent).
3. If no PR exists, say so and offer to review branch commits/diff directly.

2) Gather context

Collect:

• PR title, description, status, reviewers
• commit list on the branch
• diff summary by file/directory
• full diff vs base branch
• PR checks/status contexts (especially the Chromatic UI Review check URL if present)

3) Build a logical walkthrough

Present changes in structural order, not commit order:

1. entry points/interfaces
2. core logic and data flow
3. integrations/callers
4. end-user-facing behavior (UI/UX changes and logging/observability impact)
5. tests and safeguards
6. docs/tooling/config

For each section, explain:

• what changed
• why it changed
• impact/risk
• how it connects to the rest of the architecture

For end-user-facing sections, additionally explain:

• user-visible behavior changes (empty states, loading states, errors, copy, visual hierarchy)
• logging/telemetry changes and how they affect operators or debugging workflows
• rollout/regression risk for real users

4) Naming and terminology pass (required)

For every new or renamed symbol (files, functions, types, options, flags, user-facing terms):

• map it to existing naming conventions
• call out mismatches, ambiguity, or overload with existing terms
• state whether the name reinforces existing architecture concepts
• propose concrete alternatives when a name is weak

5) Design pattern alignment

Explicitly classify whether the PR:

• follows an existing pattern (name it), or
• introduces a new pattern (call this out clearly)

If new pattern:

• explain why it is needed
• compare against existing patterns
• describe migration/consistency implications

6) UI checks and Chromatic link (required when UI changed)

If the PR includes UI changes:

• inspect PR checks and look for the Chromatic UI Review check
• include the Chromatic UI Review URL in the walkthrough
• if the check is missing or not yet available, state that explicitly

If the PR has no UI changes:

• explicitly say "No UI changes detected; Chromatic link not required."

7) Deep-dive prompts

When you encounter a complex subproblem, pause and ask:

• "Do you want to dig deeper into <topic> now, or continue the walkthrough first?"

Use this at most once per major section unless the user asks for more.

8) Required ending

End with two short lists:

• Key areas: the most important components and decisions
• Skipped/Lightly covered areas: anything not deeply analyzed yet (or explicitly "None")

Output template

Use this shape:

# PR Walkthrough: <title>

## 1) Scope and intent
...

## 2) Structural walkthrough
### 2.1 <area>
- Change:
- Impact:
- How it works:

```<language>
// relevant snippet

2.2

...

3) Naming and terminology review

• Aligned names:
• Potential mismatches:
• Suggested renames:

4) Pattern alignment

• Existing pattern(s) used:
• New pattern introduced:
• Implications:

5) End-user-facing review

• UI changes:
• Logging/observability changes:
• Chromatic UI Review:

6) Key areas

• ...

7) Skipped/Lightly covered areas

• ...

## Guardrails

- Keep explanations concrete and code-grounded.
- Prefer short snippets over large dumps.
- Distinguish facts from assumptions.
- If information is missing (no PR body, missing tests, unclear rationale), say so explicitly.
- Do not claim a Chromatic link exists unless you found the actual check URL.