git-mr-summary.md

name	git-mr-summary
description	Generate concise developer friendly, paste-ready MR/PR summary from current branch changes only — includes before/after screenshot table, file-by-file summary, testing instructions, and an edge cases checklist table. Use when the user mentions "merge request", "MR description", "PR description", "write up my changes", "summarize my branch", "changes for review", or wants to document what's on their branch.
argument-hint	[base-branch]
allowed-tools	Bash Glob Read AskUserQuestion

MR / PR Summary

Generates a complete, paste-ready merge/pull request description covering all changes on the current branch.

Instructions for Claude

When the user invokes this skill:

Step 1: Gather Branch Diff

Determine the base branch:

• Use the argument passed to the skill if provided
• Otherwise detect it from git:

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'

If that returns nothing (remote HEAD not set), fall back to trying main, master, then primary.

git log origin/<base-branch>..HEAD --oneline
git diff origin/<base-branch>..HEAD --name-only

If no changes are found, notify the user and exit:

ℹ️  No changes detected against <base-branch>. Nothing to summarize.

Step 2: Infer UI Changes

Scan the changed file list for files that indicate visible UI changes:

• Any .tsx, .jsx, or .vue file whose name does NOT end in .test.* or .spec.*
• Any .css, .scss, or *.styles.ts / *.styles.js file

Always use the AskUserQuestion tool for this step — never skip it silently.

If UI component files were detected, list them in the question text so the user knows what was found. If none were detected, still ask — the user may want a screenshot table anyway.

Ask:

"Should I include a Before/After screenshot table in the MR description?
(You'll fill in the actual screenshots manually after generating the template)"

With options:

• Yes — 2-column (Before / After) — standard two-shot comparison
• Yes — 3-column (Context / Before / After) — useful when multiple scenarios need labelling
• No — skip — no screenshot table needed

Step 3: Detect Stories / Docs

Scan changed files for a corresponding story or documentation file:

• Look for <ComponentName>.stories.* or <ComponentName>.story.* anywhere in the diff
• Also check sibling __stories__/, stories/, or storybook/ directories

If a story file is found, note the component/story name to reference in testing instructions.

If no story file is found, use the AskUserQuestion tool to ask:

"I couldn't detect a Storybook story for the changed components.
Is there one available?"

With options:

• Yes — I'll provide the name — user types the story name via the "Other" input
• No — skip Storybook reference — omit the Storybook step from testing instructions

Step 4: Build the Diff Summary

Read the full diff to understand what changed:

git diff origin/<base-branch>..HEAD -- <src-dir>/

Use src/ as the default directory; if the project uses a different convention (e.g. app/, lib/), infer it from the changed file paths.

Group changes by file and summarize:

• New files: what they do
• Modified files: what changed and why
• Deleted files: why removed

Step 5: Generate the MR Description

Output the following markdown, filled in from the gathered information.

# Summary of Changes + Testing Instructions

<1–3 sentence overview of what this branch does and why>

---

## Before / After

<!-- ONLY include this section if the user confirmed UI changes in Step 2 -->

<!-- 2-column version -->

| Before              | After               |
| ------------------- | ------------------- |
| <!-- screenshot --> | <!-- screenshot --> |

<!-- 3-column version (with context) -->

| Context        | Before              | After               |
| -------------- | ------------------- | ------------------- |
| <!-- label --> | <!-- screenshot --> | <!-- screenshot --> |

---

### Changes

**`<path/to/file.ts>`** (new | updated | deleted)

-   <bullet describing what changed and why>
-   <additional bullets as needed>

<!-- Repeat for each changed file, grouped logically -->

---

## Testing Instructions

### Unit Tests

```bash
<project test command> <changed source files>
```

Expected: all related suites green.

### Manual Testing

1. Open the **<StoryName>** story in Storybook and verify the component renders correctly.
    <!-- If no story: remove this step -->
2. <Additional manual steps specific to the changes>

### Edge Cases

| Team Lead | Tester 1 | Tester 2 | Scenario               | Expected           |
| --------- | -------- | -------- | ---------------------- | ------------------ |
| ☐         | ☐        | ☐        | <scenario description> | <expected outcome> |
| ☐         | ☐        | ☐        | <scenario description> | <expected outcome> |

<!-- Add one row per meaningful edge case — aim for 4–8 rows -->

Step 6: Populate Edge Cases

Based on the diff, generate meaningful edge case rows covering:

• Null / empty data states
• Boundary conditions (min/max values, thresholds)
• Error states
• Mixed states (e.g. some items completed, some not)
• Mobile vs desktop if UI changed

Aim for 4–8 rows. Each row must have a concrete scenario and a specific expected outcome.

Step 7: Output

Print the completed markdown to the conversation so the user can copy-paste it directly into GitLab, GitHub, or Bitbucket.

Do NOT push or update the MR/PR automatically — output only.

Table format rule — CRITICAL: All tables MUST be output as raw GitHub-flavored markdown pipe tables. Never use ASCII box-drawing characters (┌, ─, ┬, │, ├, ┤, └, ┘, etc.). The correct format is:

| Column A | Column B |
| -------- | -------- |
| value    | value    |

This applies to every table in the output: Before/After, Edge Cases, and any others.

---

Example Invocation

/git-mr-summary
/git-mr-summary main
/git-mr-summary feature/my-base-branch

---

Notes

• The screenshot table cells are always left empty — the user fills them in after generating
• Edge case rows are generated from the diff; the user can add/remove rows before pasting
• Infer the test command from the project (npm test, yarn test, pytest, go test ./..., etc.) by checking package.json, Makefile, or pyproject.toml if needed