Anthony Bordonaro

Explain Diff Prompt

Prompt
promptsgitcode-reviewworkflow

Large PRs are hard to review because the diff shows what changed but not why. Reviewers scan 15 files, try to reconstruct intent from variable names and code patterns, and miss things. This prompt produces a narrative explanation that makes reviews faster, more accurate, and less likely to generate "why didn't you do X?" comments.

Different from the Changelog Generation prompt: changelogs are for users and describe outcomes. This is for reviewers and describes implementation decisions.

The prompt

Explain the diff for this branch. I need a clear summary for PR reviewers who will read this alongside the code.

## Steps

1. Run `git diff main...HEAD --stat` first to assess the scope, then `git diff main...HEAD` for the full diff
2. Run `git log main..HEAD --oneline` to see the commit history
3. Read each changed file and understand the purpose of the changes

## Output format

### Summary
[2-3 sentences: What does this PR do? What problem does it solve? What's the approach?]

### Changes by file

**[file path]** (new/modified/deleted)
- [What changed in this file and why]
- [If the change relates to other file changes, explain the connection]

**[file path]**
- [What changed and why]

(Group related files together if they represent one logical change — e.g., "Updated all 5 page files to use the new SeoHead component" rather than listing each page's identical change separately)

### Key decisions
- [Any non-obvious technical decisions and why they were made]
- [Alternatives that were considered but rejected, and why]

### Testing
- [How were these changes tested? What should reviewers verify?]
- [Any areas that need manual testing vs automated coverage?]

## Rules
- Write from the author's perspective ("I created X because Y"), not the code's perspective ("X was created")
- Lead with the WHY. The reviewer can see the WHAT in the diff.
- Group related files into logical changes. Don't list 10 files that all got the same mechanical update individually.
- If a file was renamed or moved, say so explicitly — it's easy to miss in a diff
- If something was deleted, explain why it's safe to remove
- For refactors, explain what the code looked like before and after at a conceptual level
- Flag anything reviewers should look at carefully (tricky logic, performance implications, security considerations)

Example output

### Summary
Adds a role-based permission system to the API. Previously all
authenticated users had full access; now endpoints check user
roles before allowing mutations. Read operations remain open to
all authenticated users.

### Changes by file

**lib/permissions.js** (new)
- Central permission checking module. Maps roles (admin, editor,
  viewer) to allowed operations. Intentionally simple — a role
  is an array of allowed actions, checked with .includes().

**middleware/auth.js**
- Added requireRole() middleware that wraps the existing
  requireAuth(). Extracts role from the JWT claims added in
  the auth refactor last sprint.

**routes/posts.js, routes/users.js, routes/settings.js**
- Added requireRole('editor') to all mutation endpoints (POST,
  PUT, DELETE). GET endpoints unchanged — still just requireAuth().

**__tests__/lib/permissions.test.js** (new)
- Tests for role hierarchy and edge cases (unknown role, missing
  role claim in JWT, expired tokens).

### Key decisions
- Flat role list (not hierarchical) because we only have 3 roles.
  If roles grow beyond 5, consider a permission matrix instead.
- Permissions checked in middleware, not in route handlers, so
  it's impossible to forget the check when adding a new route.

### Testing
- Unit tests cover the permission module. Integration tests for
  the middleware are in the existing auth test suite.
- Reviewers should verify: the role claim name matches what the
  auth service actually puts in the JWT (I used `role`, not `roles`).

When to use it

  • Before requesting review on a PR with 5+ changed files
  • When the PR spans multiple concerns and the commit history doesn't tell a clean story
  • When you're opening a PR against a repo where you're not the primary maintainer — context matters more
  • When the diff includes refactoring alongside feature work and it's hard to tell which is which

When NOT to use it

  • Single-commit PRs with clear commit messages — the commit message is the explanation
  • Automated dependency bumps or formatting changes — the diff is self-explanatory

Tips

  • Run this prompt after your code is done, not during development. The explanation should describe the final state, not the journey.
  • The "Key decisions" section is the most valuable part for reviewers. It preempts "why didn't you do X?" comments and saves entire comment threads.
  • If the output is longer than two screens, the PR is probably too large. Consider splitting it.
  • Use --stat before the full diff so Claude understands the scope before diving into details. This helps it group changes more intelligently.
Back to AI Toolkit