pr

Files (1)

• SKILL.md

SKILL.md (first lines)

# Reviewable Pull Request

Prepare a pull request body that lets a human understand the change quickly, verify that it works, and spend review time where risk is highest. This skill improves the review narrative; it does not replace code review or validation.

## When to Use

Use when:

- A branch has a meaningful diff and needs a new or updated PR body.
- The reviewer needs the shape of a refactor, flow, or integration explained.
- The change has evidence and rollback implications worth making explicit.

Load `draft-pull-request` for repository preflight, branch handling, and `gh` publication rules. Reuse an existing PR instead of opening a duplicate.

## Required Inputs

Before writing, gather:

- The authoritative spec, issue, plan, or ticket graph.
- The complete diff against the PR base.
- The actual commands run and their output.
- Any screenshots, logs, or before/after behavior available.
- If a skill or workflow changed, the original input plus the pre-edit and post-edit outputs.
- The current PR template and existing reviewer notes.

Never claim a test, screenshot, or manual check that was not actually run.

## Body Template

Use these sections unless the repository's template requires equivalent headings:

```markdown
## Summary

<the smallest visual that explains the change>

## Evidence

- **Before:** <failing test, old output, old screenshot, or baseline behavior>
- **After:** <passing test, new output, new screenshot, or verified behavior>

## Merge Danger

**Door:** <two-way or one-way>

**Blast Radius:** <one-word scope>

<what can break, what rollback restores, and where careful review matters>
```

### Summary: show the shape

Choose one small visual, not a prose dump:

- **Call tree** for runtime control flow.
- **Component tree** for UI changes.
- **File tree** for ownership or layout changes.
- **Diff sketch** for a focused behavior change.
- **Mermaid sequence or flow** for cross-component data movement.
- **Pseudocode** for an algorithm or state transition.

Example:

```text
implement-spec
  read spec + ticket graph
  frontier -> isolated workers
    ticket implementation + tests
  merge verified commits
  code-review integration branch
```

Keep only the files, calls, states, and boundaries needed to understand the change. Use the domain terms from `GLOSSARY.md` when the repository has one.

### Evidence: before and after

Evidence should be execution-based whenever possible:

```markdown
- **Before:** `pytest tests/test_export.py::test_csv` — failed: endpoint missing
- **After:** `pytest tests/test_export.py::test_csv` — passed
- **Full check:** `pytest -q` — 142 passed
```

For visual work, prefer screenshots. For bug fixes, show the original reproduction and the regression check. If there is no meaningful before state, say so and provide the strongest available verification instead of manufacturing one.

For skill changes, show the learning loop rather than only the edited Markdown:

```markdown
- **Input:** <stable task or fixture>
- **Before:** <output from the previous skill>
- **Human edit:** <decision the user made and why>
- **After:** <output after updating the skill>
- **Rerun:** <same input compared against the intended result>
```

Prefer a decision rule with boundaries over a literal preference. If the lesson can be checked mechanically, include the lint/test/hook that now enforces it.

### Merge Danger: risk, not drama

Classify the door:

- **Two-way:** reverting the commit restores the prior state without external cleanup.
- **One-way:** it changes external state, data, contracts, migrations, messages, or other effects that a revert cannot fully undo.

Name the blast radius plainly: `single-command`, `one-service`, `shared-library`, `data`, `all-users`, or another accurate scope. Mention rollback steps, migration order, compatibility concerns, and the most important review seam.

## Publication

After writing and checking the body:

1. Use the `draft-pull-request` workflow to create or update the PR with `--body-file`.
2. Verify the returned PR URL, title, base, head, and draft state.
3. Report the exact validation results and any environment-only blockers.

## Common Pitfalls

1. Writing a paragraph where a small diagram would make the change obvious.
2. Listing tests without showing the relevant before/after result.

From jellydn/my-ai-tools, MIT.

More from jellydn/my-ai-tools