# Mr Template

> Generate a review-optimized MR/PR description from the diff between the current branch and main, following the repo's git-flow conventions. Use when opening a merge request, drafting a PR description, or summarizing a branch for review.

- Skill: `espressif/mr-template` (Agent Skill)
- Install (CLI): `npx skillmds@latest add espressif/mr-template`
- Raw SKILL.md: https://api.skillmd.com/api/skills/espressif/mr-template/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: espressif (https://skillmd.com/u/espressif)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/espressif/mr-template

---


Generate a merge-request description for the **current branch** relative to `main`. Return the template only. Do not create commits, push, or open an MR.

## Scope: this branch vs main

Read the full branch-to-main delta before writing:

1. `git rev-parse --abbrev-ref HEAD`: confirm the current branch (never operate on `main`).
2. `git log HEAD --not main --pretty=format:%s`: commit subjects unique to this branch (the "what changed" spine).
3. `git diff main...HEAD --stat`: which files changed and the change size.
4. `git diff main...HEAD`: the actual hunks. Base the description solely on these.
5. If the branch has no commits ahead of `main` (empty step 2), stop and tell the user there is nothing to describe.

Do not run `git add`, `git commit`, `git push`, or any MR/PR-creation command. Output text only.

## Core principle: manage the reviewer's attention

A description optimizes for **review speed**. Orient the reviewer in 30 seconds: answer *what changed, why, and where do I start reading?* before they open the diff. A small PR with a long description is the fastest way to make a reviewer skip it. Scale the description to the diff.

## Title

Active voice, present tense, full scope. Match the `type(scope):` vocabulary from the branch commits when it fits.

| Good | Bad |
| --- | --- |
| Add user authentication | Added user authentication |
| Fix memory leak in cache | Fixing memory leak |
| Use Redis for session lookup instead of DB query | Update session.py |

## Template

Emit exactly these sections. Drop a section only when the branch has nothing for it (e.g. no tests changed: keep Testing but state what was run).

```
[Title]

## TL;DR

One or two sentences. What changed and why, at a glance.

## Problem/Task

The problem or task this branch addresses. If a ticket fully explains it, link it and write one sentence.

## Change Overview

The design of the change: the shape of the solution, key decisions, and where to start reading. Not a file list.

## Testing

How the change was verified: commands run, cases covered, manual checks.
```

## Writing rules

- **Active voice, present tense.** "X overrides Y", not "Y is overridden by X."
- **Front-load keywords.** Put the most important word in the first two words of each paragraph and header.
- **Omit needless words.** Cut "in order to", "the fact that", and hedges ("rather", "quite", "very").
- **Concrete beats abstract.** "showed 71/113 (63%) instead of 71/160 (44%)" lands harder than "showed an inflated percentage."
- **Paragraphs 2 to 4 lines.** Long blocks get skipped; one-line fragments read as noise.
- **Bold sparingly.** At most one bolded headline per bullet. Bold everything and nothing stands out.
- **No em-dashes.** Use a comma, colon, parentheses, or two sentences instead.
- **No emojis.** Anywhere.
- **No jargon or buzzwords.** Skip "leverage", "robust", "seamless", "utilize", and any internal shorthand a reviewer would not recognize. Plain words.
- **No exclamation marks.** State facts, not enthusiasm.

## The diff-complement test

The description is the **complement** of the diff, not a summary. For every sentence ask: *could a reviewer learn this by reading the diff?* If yes, cut it.

Cut every time:
- **File-by-file narration.** "In foo.py changed X, in bar.py changed Y." The stat and diff already show this.
- **Implementation play-by-play.** "First I added a helper, then called it from ..." Describe the design, not your steps.
- **Motivation the reviewer already knows.** If the ticket explains it, link it and write one sentence.
- **Restating type/signature changes.** Say *why* a signature changed, not that it did.
- **Defensive disclaimers.** "First pass", "open to suggestions." Put specific asks in Change Overview as a focus area.
- **Commit-message archaeology.** "In the first commit, then in the second ..." Describe the final state.

## Never

- No `Co-Authored-By` trailers or any authorship note.
- No "Generated with Claude Code" or any AI/Claude/agent/assistant attribution, anywhere.
- No mention of Claude, AI, agents, or assistants.
- Do not open with "This PR introduces/adds/implements ...", "In this pull request ...", or "This change ...". Start with the problem, the action, or the component name.
- No "In conclusion", "Overall", or "In summary". End with a next step or a final fact.

## Self-review before output

Re-read the draft and revise until clean:
- Run the diff-complement test on every sentence; cut what the diff already shows.
- Title is active voice, present tense, full scope.
- No forbidden opener, no summary closer, no AI attribution.
- No em-dashes, emojis, exclamation marks, or filler jargon.
- Length proportional to the diff. Trim a verbose description on a small change.

## Output

Print the final MR description in a fenced code block, ready to paste. Do not create commits or open an MR unless the user explicitly asks. Even then, per `.claude/rules/git-flow.mdc`, all changes land via MRs off `main`. Never commit directly to `main`.