pr-description

Files (1)

• SKILL.md

SKILL.md (first lines)

# PR Description

Create an accurate, reviewer-focused pull request description from the repository's current changes.

The final result must explain the change in short paragraphs and focused bullets, state whether it could change scientific conclusions, and focus attention on meaningful behavior and design decisions. When useful, choose a compact call diagram, diff-style comparison, pseudocode explanation, or directed acyclic graph (DAG) to make the change easier to understand.

## When to use

Use this skill when the user asks to:

- write or improve a pull request description;
- summarize the current branch or diff;
- explain what changed for reviewers;
- document newly added or modified execution paths;
- prepare text for `gh pr create` or `gh pr edit`.

Do not use it as a substitute for a full correctness or security review. Report important issues noticed during analysis, but keep the primary output focused on describing the change.

## Operating principles

1. Ground claims in source code, history, recorded validation, or supplied context. Distinguish inference from verified facts; never invent evidence or references.
2. Explain intent and behavior for a reviewer who has not followed the implementation work.
3. Use the analysis below to decide what matters; do not report every inspection step or finding in the PR description.
4. Keep the result proportional to the change. Headings are optional, but the scientific impact statement is required.
5. Do not modify repository files unless the user explicitly asks.
6. Do not create or update a remote pull request unless the user explicitly asks.

## Inputs and scope

Determine the review range in this order:

1. Use a range explicitly supplied by the user.
2. If a pull request already exists for the branch, use its base branch and metadata when available.
3. Otherwise identify the repository's default branch and compare its merge base with `HEAD`.
4. If no base can be determined safely, explain the limitation and use the visible working-tree and staged changes.

Include, as applicable:

- committed changes on the current branch;
- staged changes;
- unstaged changes, when the user asks about the working tree;
- relevant added, modified, renamed, or deleted files;
- tests and documentation changed as part of the same work.

Exclude unrelated generated files, vendored dependencies, lockfile churn, and formatting-only changes from detailed explanation unless they materially affect the PR.

## Repository inspection

Use the repository's available tools to inspect:

- repository status and current branch;
- default or target branch;
- commit list and commit messages;
- diff summary and full diff;
- changed files and relevant surrounding source;
- project guidance such as `AGENTS.md`, `CONTRIBUTING.md`, and PR templates;
- tests, configuration, migrations, API definitions, and documentation affected by the change.

Do not assume that `main` is the base branch.

## Analysis workflow

### 1. Establish the change boundary

Establish the branch, comparison base, included commits and files, and whether uncommitted changes are in scope.

### 2. Build a semantic change inventory

Group changes by purpose rather than file order. For each group, identify what changed, why it was needed, how it works, and any compatibility or operational consequences. Include reused components only when they help explain the change.

### 3. Understand changed logic and relationships

For executable code that is new or modified:

1. Read the complete changed functions and relevant surrounding code, not only the diff hunks.
2. Compare previous and current logic, including conditions, calculations, dependencies, and failure behavior.
3. Follow calls and data dependencies only as far as needed to explain the change. Include unchanged code only for necessary context.
4. Verify relationships from source code; names, imports, and directory structure alone are not evidence.

When symbol status helps explain a diagram, label symbols as:

- `[NEW]` for symbols introduced by the change;
- `[MODIFIED]` for existing symbols whose executable behavior changed;
- `[EXISTING]` for unchanged dependencies included for context.

When status is ambiguous, omit the status rather than guessing.

### 4. Assess impact and risk

Include `Scientific impact: NONE`, `Scientific impact: MINOR`, or `Scientific impact: MAJOR` near the top, followed by exactly one sentence in plain English explaining why. Rate the highest plausible effect of the whole PR on scientific results or conclusions:

- **NONE:** No plausible change to scientific results or their interpretation. Explain what keeps the analysis unchanged; a "docs" or "refactoring" label alone is not evidence.
- **MINOR:** A limited scientific result or its presentation could change, but the main conclusions are not expected to change. Name the affected result.
- **MAJOR:** The main results or conclusions could change, or the available evidence cannot rule that out. Name the affected analysis or the uncertainty.

Use only one of these three words as the rating. Do not add a second rating or a separate impact paragraph.

Assess the whole PR: a scientific change remains relevant even if most files are documentation or cleanup. Documentation that changes analysis instructions or scientific interpretation can also affect conclusions.

Distinguish potential impact from demonstrated impact. Say conclusions actually changed only when a comparison of results supports that claim; report the observed change and the comparison's scope. Passing tests alone does not establish that conclusions are unchanged. For code reorganization, distinguish an intention to preserve results from evidence that results are preserved.

Keep this separate from operational risk: a reliable implementation can intentionally change scientific conclusions. A known failed or invalid scientific computation is an implementation failure, not merely an uncertain scientific impact; state the failure and do not present partial outputs as successful.

Check for:

- public API, schema, protocol, or configuration compatibility;
- migrations and rollback implications;
- authentication, authorization, privacy, and security effects;
- concurrency, retries, idempotency, and transaction boundaries;
- performance-sensitive loops, queries, allocations, or network calls;
- changed defaults, feature flags, or deployment ordering;
- new failure modes and error handling;
- test gaps or unverifiable assumptions.

Mention only risks that are grounded in the diff or surrounding code.

### 5. Verify validation evidence

Inspect relevant test changes and, when permitted, run the narrowest useful verification commands first.

From tobywise/agent-skills, MIT.

More from tobywise/agent-skills