pr-description

PR Description Generator

When creating or updating a pull request, ALWAYS generate a comprehensive, visual description following the format below. The goal is that a reviewer can understand the entire PR in under 60 seconds by scanning diagrams and bold titles.

Process

1. Identify the base branch (usually master or main)
2. Read ALL commits in the branch: git log --oneline <base>..HEAD
3. Read the full diff against base: git diff <base>...HEAD --stat for an overview
4. Read the actual code changes for key files: git diff <base>...HEAD -- <file> to understand the logic
5. Categorize changes into: Features, Bug Fixes, Performance, UI/UX, Refactoring, Testing, Documentation
6. Create Mermaid diagrams to visualize the changes (see Diagram Guidelines below)
7. Write the description in English regardless of the conversation language

PR Description Template

## Summary

[1-3 bullet points explaining WHAT changed and WHY, in plain language]

## Diagrams

### [Diagram title - e.g., "Data Flow", "Bug -> Fix", "Architecture Change"]

```mermaid
[Appropriate diagram type - see Diagram Guidelines]
```

### [Additional diagram if needed - e.g., "Code Changes", "State Machine"]

```mermaid
[Additional diagram]
```

## Changes

### [Category 1] (e.g., Features, Bug Fixes, Performance)
- **[Change title]** - brief explanation of what and why
- **[Change title]** - brief explanation of what and why

### [Category 2]
- ...

## Code Changes (key files)

```mermaid
flowchart LR
    subgraph "filename.ts"
        A["line X:<br/><s>old code</s>"] --> B["new code"]
    end
```

## Test Plan

- [x] [Automated test that passes - with count if applicable]
- [x] [Another automated test]
- [ ] [Manual test step to verify]
- [ ] [Another manual verification]

### What type of PR is this?

- [ ] Refactor
- [ ] Feature
- [ ] Bug Fix
- [ ] Optimization
- [ ] Documentation Update
- [ ] Testing Coverage
- [ ] Other

## Evidence (Before/After)

<!-- Backend / API / service — run locally, exercise with real requests, capture stdout/responses, render to PNG: -->
![Working run](https://github.com/{owner}/{repo}/releases/download/pr-evidence/pr-{N}-evidence.png)

<!-- UI — run the app locally, drive the real screen with Playwright, screenshot actual rendered UI: -->
| Before | After |
|--------|-------|
| ![Before](https://github.com/{owner}/{repo}/releases/download/pr-evidence/pr-{N}-before.png) | ![After](https://github.com/{owner}/{repo}/releases/download/pr-evidence/pr-{N}-after.png) |

<!-- New component — no prior screen exists, after-only: -->
![After](https://github.com/{owner}/{repo}/releases/download/pr-evidence/pr-{N}-evidence.png)

<!-- CLI / hooks / scripts — run the real command, capture real output, screenshot it: -->
![Real output](https://github.com/{owner}/{repo}/releases/download/pr-evidence/pr-{N}-evidence.png)

<!-- Fallback only when the service genuinely cannot be run locally (hard external deps, secrets): capture from a real deployed run or emit an explicit placeholder for the author — NEVER invent or mock the image: -->
| Before | After |
|--------|-------|
| _[author: attach REAL BEFORE screenshot here — no mocks]_ | _[author: attach REAL AFTER screenshot here — no mocks]_ |