SuperAPI AI Directory

pr-description

Coding & development

View repository

Updated 11-18 22:53

About this skill

PR description

The reader reviews 50 PRs a day. They give yours about 60 seconds before they approve it, ask a question, or put it off. Cut any line that doesn't help them do one of those.

The ticket, PRD, or artifact explains why the change exists, and the diff and commits show how it was made. The description covers what they can't: what the change looks like, how to see it running, and which files to read.

Template

[ABC-123](https://linear.app/…/ABC-123) · Stacked on #897

<One sentence: what a user sees or can do that they couldn't before.>

| Before | After |
| --- | --- |
| ![Before: <screen>](./pr-shots/before-<name>.png) | ![After: <screen>](./pr-shots/after-<name>.png) |

Try it

  1. <Launch point: app, account/fixture, screen>
  2. . Expect .
  3. <Edge case: dark mode / largest text / empty state>. Expect .

Review path/to/the-file-that-matters.tsx (the rest is mechanical). Skip *.snap and locales/*.

Needs decision <Only if you're blocked on someone: one question with options, @-mention them>


Leave out every section you don't need. The smallest valid PR has a ticket link, one sentence, and a screenshot pair.

- First line: write it only when there's something to put on it. If there's no ticket, PRD or artifact, leave the source out without comment. Don't write "No ticket".
- Stack: before naming a parent or dependency PR, check it with `gh pr view <n> --json state`. Leave out any that have merged. If the base branch's PR has merged, tell the user to retarget the PR to the default branch.
- Reviewers: request them with `gh pr edit --add-reviewer <login>`. Never name a reviewer in the body ("for Jim to review"). The one exception is the @-mention under "Needs decision".

## Hard limits

- Title: `ABC-123: <Area>: <change>` in at most 60 characters (drop the ticket prefix if the repo doesn't use one), written as an imperative or noun phrase. Use one clause. A list inside it is fine ("loading, empty and error states"), but a title that joins two changes with "and" usually belongs to two PRs.
  - Bad: `ABC-411: Rows end in one chevron, icons take icon tokens and role sizes, and lists draw Divider`
  - Good: `ABC-411: Lists: one chevron, icon tokens, Divider`
- Prose: at most 80 words, not counting the image table, the Try-it steps, and file paths. Count them, and if you're over, cut content instead of rephrasing it.
- Bullets: at most 5, each at most 15 words. Past that, the reviewer should read the diff.
- Headings: no `##` unless there are 3 or more screenshot pairs. Use the bold labels from the template.

## Visual PRs need before/after screenshots

Treat a PR as visual if it touches UI code (`.tsx`, `.vue`, `.swift`, `.kt`, `.css`), tokens, copy catalogs, icons, or design-system components. A visual PR has to have screenshots. If you can't capture them, open it as a draft and tell the user which shots are still missing. Tell them in the conversation, not in the PR body.

1. After: run the branch and capture the screen the Try-it steps reach.
   - iOS simulator: `xcrun simctl io booted screenshot <path>`
   - Android emulator: `adb exec-out screencap -p > <path>`
   - Web: whatever browser automation you have (Playwright, Claude in Chrome, etc.)
2. Before: in `<tmp>`, a scratch directory outside the repo, run `git worktree add <tmp>/base $(git merge-base HEAD origin/main)`, then run it there and capture the same screen with the same data, theme, and text size.
3. Match the pairs pixel for pixel: same device, same scroll position, same fixture. Crop to the component when only one component changed. If light and dark both changed, show both as rows in the same table.
4. For motion or interaction, such as a keyboard lift or a transition, record a short `.mp4` or `.mov`, since a still can't show it.
   - `--attach` uploads video, and GitHub plays it inline. Video can't have alt text.
   - Put each video on its own line below the table, with a bold "Before" or "After" label above it. Don't put video in a table cell.
   - If the uploaded video doesn't play on the PR page, swap in a GIF inside the table.
5. Upload with `gh` (version 2.102 or later): save the shots to `<tmp>/pr-shots/{before,after}-<name>.png`, and write the body file into `<tmp>` too, so that `./pr-shots/…` in the body resolves.
   - Reference each image in the body as `![alt](./pr-shots/after-<name>.png)`.
   - Pass every file with `--attach './pr-shots/after-<name>.png#After: <screen>'` on `gh pr create` or `gh pr edit`. `gh` uploads it and rewrites the matching reference in the body to the hosted URL.
   - `gh` takes up to 50 files per command, images or video.
   - Don't commit screenshots to the repo.
   - Afterwards, check the body with `gh pr view --json body`. Any `./pr-shots/` path still in it failed to upload, so re-attach it.

Use 1 to 3 pairs, chosen for the most-changed screen. If a sweep touches 40 screens, show the 2 most representative ones and say "same change on N other screens."

## Try it: how to write the steps

- Steps are what a reviewer does in the running app. Leave unit tests out, because CI already reports them.
- Step 1 says where to start: which app, which state, which screen.
- Every step ends in `Expect <something visible>`, so the reviewer can tell whether it passed.
- Use fewer than 5 steps.
- Run every step before you include it. Never guess how to reach a state.
  - For a loading, error or empty state, find the real trigger in the code: a demo control, a fixture account, a mock flag, or a debug menu item. Name that trigger in the step.
  - If you can't run a step, and the code doesn't show how to reach its state, leave the step out. Tell the user which state you couldn't reach.
  - The user needs to know which steps you ran and which you only traced in code. Tell them that separately, not in the PR body.
- Use a numbered list instead of `- [ ]` checkboxes, which nobody ticks.

## Patterns from past PRs to cut

| Pattern | Why it goes |
| --- | --- |
| `## Summary` that restates the title | The title already says it |
| `## Linear` section paraphrasing the ticket | The link is enough |
| "Why it's needed" or "because…" when a ticket or PRD is linked | The ticket owns the why |
| "How it works" walkthroughs and lists of function names | The diff shows this. Put anything non-obvious in a code comment |
| "Second review round", "Simplify follow-ups" | Review history belongs in commits and the thread |
| "Left alone / Unchanged / Not done" lists | Keep one line only if a reviewer would otherwise ask why you didn't also change X |
| Proof of research ("I read RN 0.86's source…") | Put it in a code comment, or leave it out |
| Contrast or value tables included for interest | Keep one only under "Needs decision" |
| Third person about the author ("for Sam", "Sam's decision of 2026-10-16") | The PR is in the author's voice. Write "I" or leave it out |
| Dated attributions "(Name, YYYY-MM-DD)" | Link the thread or ticket instead |
| Line-count justifications ("Size: 478 added… over the ~500 target") | Use one "Review" line that says what to skip |
| Merge-conflict forecasts for other branches | Comment on the other PR |
| Links to agent sessions or chat transcripts | Reviewers can't open them |
| Review requests ("for Jim to review", "stays unmerged until…") | Use `--add-reviewer` and draft status instead |
| "Depends on #879" after #879 has merged | It's no longer true |
| What you couldn't do: "I couldn't run that on my machine", "this machine doesn't have a browser, so no screenshots", "tests not run locally", "not checked in the browser" | The reviewer can't act on your environment. Leave out the screenshot, step or check you don't have, and tell the user in the conversation instead |
| Hedges and filler: "now", "explicitly", "exactly", "this PR" | They add no information |

## Writing style

- Use concrete nouns a reviewer can see on screen, like "Save button", "Email only row", or "16pt chevron", instead of abstractions like "the CTA policy" or "the states rules".
- Write one fact per sentence, in the present tense.
- Use code formatting only for identifiers the reviewer will search for.
- If someone else has to make a decision, put it under "Needs decision" at the bottom, @-mention them, and keep it to 3 lines or fewer.

## Process

1. Gather `git log origin/main..HEAD`, `git diff --stat origin/main...HEAD`, the ticket ID from the branch name, the base branch if the PR is stacked, and any PRD or artifact links in the commits or conversation.
2. Check the state of every PR the stack or a dependency names, and drop the merged ones.
3. Decide whether the PR is visual. If it is, take the screenshots, and run the Try-it steps as you go. Do this before you write anything.
4. Fill in the template and delete the sections you don't need.
5. Reread it as a reviewer with 59 more PRs in the queue. For each sentence, ask whether they would approve, question, or test differently without it. If they wouldn't, delete it. Then check the word count against the limits.
6. Create or edit with `gh pr create --body-file body.md --attach …` or `gh pr edit --body-file body.md --attach …`, running it from `<tmp>` so the relative image paths resolve. Add any reviewers in the same command with `--add-reviewer`.
7. Show the user the final title and body. List any Try-it steps you couldn't run, and any screenshots or checks you couldn't produce. That list goes to the user only: the PR body never says what you were unable to do or why.

## Example rewrite

Before: a real PR body of about 2,900 characters, 3 tables, 0 screenshots. After:

```markdown
[ABC-411](…) · Stacked on #922

Row disclosures, icon colors and row dividers come from design-system primitives across the app.

| Before | After |
| --- | --- |
| ![Before: Settings](./pr-shots/before-settings.png) | ![After: Settings](./pr-shots/after-settings.png) |

**Try it**
1. Sign in as the demo user → Settings. Expect one 16pt chevron per row, and dividers inset 10pt on both sides.
2. Same screen in light mode. Expect lighter chevrons and icons (`icon.*` tokens).

**Review** `RowChevron` call sites. Everything else is a mechanical swap. Skip `*.snap`.

**Needs decision** @lead: in light mode, `icon.secondary` #b19f96 is 2.0–2.5:1 on our surfaces (WCAG floor for meaningful glyphs: 3:1). Darken the token, or keep `text.secondary` for chevrons?