pr-writer

SKILL.md

PR Writer

Write the PR body as a cover note for reviewers, not a changelog, template,
validation log, or file-by-file summary.

Inspect the Change

Requires authenticated gh. Inspect the current branch, working tree, PR,
base branch, commits, and full diff:

git branch --show-current
git status --porcelain
gh pr view --json number,title,body,url,baseRefName,headRefName
gh repo view --json defaultBranchRef

If gh pr view reports that no PR exists, continue with first-time PR
creation. For an existing PR, use its baseRefName; otherwise use the
repository default branch. Set BASE, then inspect:

git log "$BASE"..HEAD --oneline
git diff "$BASE"...HEAD

If on main or master, create a feature branch first. Ensure intended
changes are committed and review the whole branch diff, not only the latest
commit or existing PR text.

Core Rules

Describe concrete changed behavior, affected surfaces, and reviewer impact
before implementation detail.

Explain motivation, risk, tradeoffs, migration, or review focus only when
useful.

Use the smallest structure that makes the change easier to review.

Replace internal prompt or process terminology with specific behavior.

When refreshing a PR, rewrite around the current full diff without narrating
review history.

Titles

Use <type>(<scope>): <subject> or <type>: <subject>.

Allowed types: feat, fix, ref, perf, docs, test, build,
ci, chore, style, meta, license, and revert.

Describe the dominant full-branch change with the narrowest accurate type
and scope.

Use ! only when the change breaks an external contract, and explain the
affected surface in the body.

Avoid vague subjects such as update, cleanup, misc, fix stuff,
or address feedback. Do not add a trailing period.

Keep an existing title only when it still describes the whole diff.

Body Shape

Choose the minimum useful shape:

Change
Include

Small or obvious
One concise paragraph without headings.

Feature, bug fix, or refactor
Changed behavior and effect; add root cause, unchanged behavior, or non-obvious approach when relevant.

Contract or breaking change
Affected API, schema, payload, config, permission, storage, or CLI surface; include compatibility and migration guidance.

Operational, visual, or workflow change
User/operator effect, measured impact, failure modes, or flow when useful.

Broad, generated, or cross-cutting change
Organizing principle, why the breadth is necessary, and where review should start.

Default:

<What changed and what effect it has.>

<Why the approach, risk, migration, or review focus matters, if not obvious.>

For review-feedback updates, describe the resulting PR as a whole rather than
the sequence of revisions.

Reviewer Aids

Use an aid only when it reduces reviewer reconstruction work:

A compact before/after or interface example for changed contracts.

A small Mermaid diagram for async flows or state transitions.

A screenshot or recording note when visual evidence exists.

A rollout, compatibility, risk, or review-order note when reviewers or
adopters need it.

Introduce an artifact with one sentence explaining what reviewers should
notice. Omit it when prose is clearer.

Boundaries

Do not add default Summary, Changes, or Test Plan sections.

Omit routine validation unless it changes risk assessment or explains
meaningful regression coverage. For docs, skills, copy, or config changes,
omit it by default.

Do not paste commands, CI logs, validation dumps, commit logs, placeholders,
or exhaustive file lists.

Never include customer or organization names, user emails, support ticket
contents, secrets, or PII.

Use issue references only when verified from user input, branch names,
commits, PR discussion, or tracker output. Fixes <issue> closes;
Refs <issue> only links.

Create or Update

Create new PRs as drafts. Write the body to a temporary Markdown file, then run:

gh pr create --draft --title '<title>' --body-file /tmp/pr-body.md

Update existing PRs with gh api:

gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
  -f title='<title>' \
  -F body=@/tmp/pr-body.md

Refresh the title and body when follow-up commits materially change scope,
approach, breaking behavior, risk, migration, or review expectations. Skip
typo-only, formatting-only, and rename-only follow-ups.

Examples

Small change:

The AI Customizations section now starts collapsed so it does not consume
sidebar space before users need it. Expanding it preserves the existing saved
preference behavior.

Breaking contract:

Run logs now emit chunk-level records instead of one skill-level record.
Consumers that read top-level `findings` must iterate over
`chunk.findings` for each record.

Before:

```json
{"skill": "security-review", "findings": [...]}
```

After:

```json
{"schemaVersion": 1, "chunk": {"index": 1, "findings": [...]}}
```