mcpField
W
writing-pr

writing-pr

github.com/e2e-incDevelopment13.8k274 installsUpdated today
Repository

About writing-pr

A repository skill for writing concise, evidence-focused pull request titles and bodies. It gives contributors a consistent structure for explaining changes and verification without repeating the diff.

Key features

  1. 01Conventional Commits-style titles
  2. 02Outcome-focused titles
  3. 03Bullet-based change summaries
  4. 04Guidance for diagrams and code samples
  5. 05Required verification evidence

Use cases

  1. 01Drafting a PR for a code change
  2. 02Documenting visual changes with before-and-after evidence
  3. 03Summarizing benchmarks or API changes

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/e2e-inc/e2e --skill writing-pr

After installing, type/writing-prin Claude Code to confirm it loaded.

Details

From the project README

Writing a PR title and body

Reviewers skim. Put the shape of the change on the first screen, then let diagrams and code carry the detail.

Title

  • Conventional Commits, matching git log: fix(playwright): provision the browser in a runner-side prepare hook. PRs squash-merge with the number appended, so the title is the commit.
  • Mark spec or API breaks with ! (feat(config)!: ...), same as the commit.
  • Name the outcome, not the activity. "install builds with the appPath option", not "agent-device changes".

Body

Do not write essays. A few bullets on what changed and why, then evidence.

  • Bullet points for the prose you do write. One fact per bullet.
  • A mermaid diagram for anything with flow or state: runner phases, engine hooks, replay paths, before/after architecture.
  • Code samples: the new API, sample usage in a test file, or the key internal snippet. Fenced blocks with a language tag.
  • Code refs (packages/e2e/src/run/execute.ts:42, GitHub permalinks) instead of paraphrasing code.
  • Visual changes, direct or indirect (CLI output, reporter output, docs pages): a before/after table with uploaded images or videos.
  • Benchmarks: a before/after table. Baseline is the target branch, candidate is the PR.
  • Spec changes: name the chapter, schema, and suiteVersion bump in one bullet so the reviewer can check them together.
  • A ## Issue section with Fixes #123 when the PR resolves an issue. Required on community fix, chore, test, perf, ci, build, and revert PRs (CONTRIBUTING.md, Pull requests).
  • A ## Verified section, required on every PR:
    • First line: Ran it locally: yes, or Ran it locally: no - <why> (docs typo, CI-only, a device you do not have).
    • With yes: the verify surface, the command you ran, what you saw, and the CLI output, screenshots, or video showing it work.
    • A fix PR with yes also shows the bug and the fix side by side in a | main | this branch | table.
    • Upload media with gh 2.99+ --attach: reference images in the body as markdown (![after](./after.png)) and pass each file as --attach; gh uploads them and rewrites those paths. Do not write video paths in the body: attached videos are appended at the end and render as players.

Leave out

  • "I ran lint/tests" lists. CI reports that; ## Verified is for what CI cannot see.
  • Intermediate history. Squashed 6k lines down to 1k, refactored twice, renamed midway: none of it lands. Only the final aggregate squash-merge commit exists, so only that gets commentary.
  • Line-by-line restating of the diff.
  • Checklists nobody asked for, sign-offs, filler.

Templates

Before/after for visuals:

| Before | After |
| --- | --- |
| ![before](url) | ![after](url) |

Verified, for a fix (local image paths become uploaded assets with --attach):

## Verified

Ran it locally: yes
- testbed, `e2e run tests/scroll.e2e.ts --video`: the new test fails on main
  and passes here

| main | this branch |
| --- | --- |
| ![bug](./main.png) | ![fixed](./branch.png) |

gh pr edit <pr> --body-file body.md --attach ./main.png --attach ./branch.png --attach ./video.webm

Benchmarks:

| Scenario | main | this PR | delta |
| --- | --- | --- | --- |
| testbed default suite | 41s | 23s | -44% |

Flow:

```mermaid
flowchart LR
  A[collect] --> B[schedule]
  B --> C{cache hit?}
  C -- yes --> D[replay]
  C -- no --> E[act]
```

Big changes

For truly impressive, difficult, high-risk, or wide-scoped changes, write the body like a technical blog post: context, the problem, the approach, code samples, diagrams, before/after, images. Storytelling is fine here. The rules above still hold: run output only as ## Verified evidence, no intermediate history.

Voice

Run the unslop pass on the final text before posting. PR-specific tells to catch:

  • "This PR introduces...", "comprehensive", "robust", "seamless", "ensures", "leverages", "enhances".
  • Bold label lists that restate the line (**Performance:** Performance...).
  • Em dashes. Use a comma, a colon, or a new sentence.
  • Bullets padded to three because three felt right.
  • A summary that could be pasted unchanged into another repo's PR.

Comments

Markdown supported