docs-pr

name	docs-pr
description	Write PR titles and descriptions for Expo docs repository pull requests. Use when the user asks to "write a PR description" or "create a PR" for expo/docs; supports a --short mode that outputs only the How section.
argument-hint	[--short]
version	1.0.0

docs-pr

Default length:

Always provide a default PR title and description that is short and concise enough as an output. Treat the this as the baseline rather than a modifier.

If Why + How + Test Plan together exceed ~6 sentences, cut.

Short mode (--short)

When the user passes --short or asks for the "short version", output only the # How section and nothing else. Skip the title, Why, Test Plan, and Checklist.

PR Title Format

[docs] Short description of the change

• Always prefix with [docs]
• Keep it under 70 characters
• Use imperative mood (e.g., "Fix", "Add", "Remove", "Update")

PR Description Format

The description must use these exact sections in this order, each as an H1 (#):

# Why

# How

# Test Plan

# Checklist

Why

• Default: 1 sentence stating the motivation. Add a second sentence only when the problem cannot be understood without it (e.g., quoting an error message or linking an issue).
• Otherwise, if a linear task exists, use Fix <issue-number>.

How

Always a bulleted list of the changes, one bullet per change, terse. Lead each bullet with an imperative verb (Add, Fix, Update, Remove). Use inline code formatting for file names, function names, and config values. Do not write a prose paragraph. For a PR spanning 3+ unrelated areas, group the bullets under bold sub-headings, one bullet per line.

Test Plan

Default: 1-2 sentences in plain prose (no checkboxes, no nested lists). Name the specific page or feature to exercise and the expected result. Skip anything a reasonable reviewer would assume.

Checklist

Always include this exact checklist at the end:

- [ ] I added a `changelog.md` entry and rebuilt the package sources according to [this short guide](https://github.com/nicknisi/dotfiles/wiki/Pull-Request-Guidelines).
- [ ] This diff will work correctly for `npx expo prebuild` & EAS Build (eg: updated a module plugin).
- [ ] Conforms with the [Documentation Writing Style Guide](https://github.com/expo/expo/blob/main/guides/Expo%20Documentation%20Writing%20Style%20Guide.md).

When generating the final output, use # (H1) for the Why, How, Test Plan, and Checklist headings, not ## (H2).

Example

# Why

Running `pnpm lint` prints this warning on every run:

> (node:40346) ESLintPoorConcurrencyWarning: You may disable concurrency or use a numeric concurrency setting to improve performance.

It is a known, purely informational warning from ESLint v9+ that does not affect linting results, and suppressing it keeps the output readable.

# How

- Add `NODE_OPTIONS='--no-warnings'` to the `lint` script to suppress the `ESLintPoorConcurrencyWarning` noise from `pnpm lint` output.

# Test Plan

Run `pnpm lint` and confirm no warning is printed.

# Checklist

- [ ] I added a `changelog.md` entry and rebuilt the package sources according to [this short guide](https://github.com/nicknisi/dotfiles/wiki/Pull-Request-Guidelines).
- [ ] This diff will work correctly for `npx expo prebuild` & EAS Build (eg: updated a module plugin).
- [ ] Conforms with the [Documentation Writing Style Guide](https://github.com/expo/expo/blob/main/guides/Expo%20Documentation%20Writing%20Style%20Guide.md).

Guidelines

• Never use em dashes or en dashes. Use hyphens, commas, or separate sentences instead.
• Do not enumerate every file touched. Group related edits into one phrase ("registers paths and titles in common/i18n.ts") rather than listing each function or constant separately.
• Generate text only. Never commit, push, or create the PR; the user handles git.