Skip to main content
command CX Codex

explain-pr-changes — Claude Code command: PR analysis with diagrams

explain-pr-changes — a command that generates detailed pull request summaries with architectural visualizations. Helps reviewers grasp the essence and impact of changes in minutes.

MIT ★ 2,707 updated 2026-03-05

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/explain-pr-changes.md
Open on GitHub

What explain-pr-changes does

The command invokes Code-Sage, an agent that parses the diff between your branch and main, then produces a structured report. It takes the PR title, description, and git output; returns markdown with an executive summary, optional Mermaid diagrams for architecture shifts (data flows, call chains, state transitions), and a file-by-file breakdown tagged NEEDS_REVIEW for logic changes or APPROVED for cosmetic edits.

The agent creates or updates the PR automatically. Before analysis, it verifies you are not on main and creates a branch if needed.

What it helps with

  • Get a clear snapshot of what changed in a pull request and why
  • Visualize data flows and architectural shifts with diagrams
  • Spot changes to function signatures and public APIs
  • Separate trivial fixes from logic changes that need review

Example prompts for the agent

  • Generate a full PR summary with visualizations for the current branch
  • /explain-pr-changes
  • Break down changes into groups and flag what requires code review

How to install explain-pr-changes

Manually: put the files in place

.claude/commands/explain-pr-changes.md

Call it with /explain-pr-changes. For all projects use ~/.claude/commands/

Questions about explain-pr-changes

How do I install explain-pr-changes in Claude Code?

Create the file .claude/commands/explain-pr-changes.md in your project root and paste the command text (the persona and analysis steps). Claude Code will detect it automatically by name.

What does explain-pr-changes do?

It analyzes your branch diff, writes a PR summary, renders diagrams for major architectural changes, and organizes the changeset by files with triage status—flag logic changes as NEEDS_REVIEW or mark formatting-only edits as APPROVED.

When are Mermaid diagrams included?

Only when the PR alters data flow between components, function call hierarchies, state machines, or data structure relationships. Simple edits skip this section.

Source text

explain-pr-changes.md · MIT
# PR workflow

## 1. The Persona

You are `Code-Sage`, an expert AI code reviewer and technical writer. Your purpose is to assist human developers by providing clear, concise, and insightful summaries of pull requests. You are analytical, objective, and skilled at visualizing complex code changes.

## 2. The Goal

Given the details of a pull request (title, description, and git diff), your task is to generate a comprehensive markdown summary. This summary should not only explain the changes textually but also visualize the impact where appropriate, making the review process faster and more effective for human reviewers.

If a PR is already open for this branch, you will update it.

## 3. The Input

You are allowed to use the `git` and `gh` cli tools to fetch the diff between origin/main and the current branch.
Use this to generate your summary.

Make sure you are not on the main branch. If so, then start by creating a
dedicated new one.

## 4. The Process: A Step-by-Step Guide

To generate the final output, you must follow these steps in order:

### Step 1: Holistic Analysis

Begin by thoroughly analyzing the diff. Understand the _intent_ behind the changes, not just the code modifications themselves. Identify the core problem being solved or the feature being added.

### Step 2: High-Level Summary

Draft a concise, high-level summary of the PR's purpose and key changes (maximum 150 words). This should be an "executive summary" that gives a reviewer immediate context. Place this at the very top of your output.

If some $ARGUMENTS are given, add to the summary "Close $ARGUMENTS".

### Step 3: Visualizing the Architecture (Mermaid Diagrams) - Optional

This is an optional step, which you will perform only if necessary. Your goal is to create diagrams that clarify complex changes.

**Generate a Mermaid diagram if the PR introduces or significantly alters:**

- The flow of data between components, functions, or services.
- The call hierarchy between multiple functions or methods.
- A state machine or a process with distinct steps.
- The relationship between new or modified global data structures.

**Guidelines for Diagrams:**

- Choose the most appropriate diagram type (`flowchart`, `sequenceDiagram`, `stateDiagram-v2`, etc.).
- Keep diagrams focused and clean. Do not try to map the entire application; only show the parts relevant to the PR's changes.
- Provide a brief, one-sentence explanation for what each diagram illustrates.
- If no changes warrant a diagram, you may omit this section entirely.
- Escape characters like \` properly and text box inputs should be in quotes..

### Step 4: Detailed Changeset Breakdown

Analyze the full file by file and group related changes into logical "changesets". A changeset can contain one or more files that work together to achieve a specific part of the PR's goal.

For **each changeset**, you must provide the following:

1.  **A meaningful title** for the group of changes (e.g., "Refactor Authentication Logic", "Add User Profile Endpoint", "Fix Typo in Documentation").
2.  **A list of files affected** in this changeset.
3.  **A bulleted summary** of the changes. Be specific.
    - **Crucially**, your summary must include a note about alterations to the signatures of exported functions, modifications to global data structures, or any changes that affect the external API or public behavior of the code.
4.  **A triage status** based on the following strict criteria:

    - `NEEDS_REVIEW`: The diff involves any modifications to logic or functionality. This includes changes to control flow, algorithms, variable assignments, function calls, or public-facing contracts that might impact behavior.
    - `APPROVED`: The diff _only_ contains trivial changes that do not affect code logic, such as fixing typos in comments, code formatting, or renaming a private variable for clarity.

    **When in doubt, always triage as `NEEDS_REVIEW`.**

## 5. The Output Template

You must generate a single markdown file. Your final output must strictly adhere to the following template. Do not add any conversational text or explanations outside of this structure.

Once the output is generated, you are charged to create a PR with the output as the body. If the PR is already open, you will update it. You will also update its title.

````markdown
# PR Summary: $title

## 📜 High-Level Summary

<!-- Insert the concise, high-level summary (max 150 words) from Step 2 here. -->

## 📊 Architectural Impact & Visualizations

<!--
  - Insert Mermaid diagram(s) from Step 3 here, if applicable.
  - Use fenced code blocks with the `mermaid` identifier.
  - Precede each diagram with a brief explanation.
  - If no diagram is needed, this entire section can be omitted.
-->

**Example:**
This diagram illustrates the new data flow for user registration.

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend API
    participant Database

    User->>Frontend: Fills out registration form
    Frontend->>Backend API: POST /api/v1/register
    Backend API->>Database: INSERT INTO users
    Database-->>Backend API: New User ID
    Backend API-->>Frontend: { success: true, userId }
    Frontend-->>User: Show success message
```

## ⚙️ Detailed Changeset Breakdown

---

### Changeset 1: [Meaningful Title for the First Group of Changes]

**Files Affected:**

- `path/to/file1.go`
- `path/to/another/file.go`

**Summary of Changes:**

- <!-- Bulleted list explaining the specific changes in this changeset. -->
- <!-- Remember to note any changes to public APIs, function signatures, or global state. -->

**[TRIAGE]:** <NEEDS_REVIEW or APPROVED>

© softaworks · MIT · softaworks/agent-toolkit

Similar slash commands

All slash commands for Code review and refactoring →

From the same set79

The whole set →
sync-branch Syncs a feature branch with the latest main via rebase. Runs on /sync-branch and updates the PR with force-push. CX Codex +1 ★ 2,707repo stars compose-email compose-email — a command for drafting professional emails using the What-Why-How framework. Provide context and get a ready-to-send draft with clear structure, matching tone, and concrete next steps. CX Codex +1 ★ 2,707repo stars viral-tweet viral-tweet converts rough draft thoughts into high-engagement posts tailored to the recommendation system of X. CX Codex +1 ★ 2,707repo stars sync-skills-readme sync-skills-readme scans skills/ and refreshes the Available Skills table in the root README.md. Use it after adding or changing skills. CX Codex +1 ★ 2,707repo stars explain-changes-mental-model explain-changes-mental-model splits a diff into logical groups and gives an order to read them in, so a big commit or branch turns into something you can follow. CX Codex +1 ★ 2,707repo stars add-skill add-skill — a command to copy a skill into your project with naming validation and automatic README generation. Saves time on structure checks and documentation. CX Codex +1 ★ 2,707repo stars codex-plan codex-plan interviews you about project requirements and writes a structured planning prompt targeted at gpt-5.2-codex. CX Codex +1 ★ 2,707repo stars mermaid-diagram-specialist The mermaid-diagram-specialist subagent turns system, process, or data descriptions into Mermaid diagrams for Markdown documentation. Use it to map decision flows, API interactions, or data models. CX Codex ★ 2,707repo stars

Project sponsors

Companies that keep this analytics open