# Reviewable Pr

> Prepare PRs for review: clean noisy history, improve descriptions, add reviewer guidance. Trigger: 'make easy to review', 'tidy PR', 'clean up commits', 'annotate diff'.

- Skill: `aryaminus/reviewable-pr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aryaminus/reviewable-pr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aryaminus/reviewable-pr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: aryaminus (https://skillmd.com/u/aryaminus)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aryaminus/reviewable-pr

---


# Reviewable PR

Prepare a PR so a reviewer can quickly understand intent, risk, and key files — without changing code behavior.

## Do NOT use when
- Doing normal coding or bug fixing
- Running security or quality reviews (use those skills directly)
- Making behavior changes (this skill only improves reviewability)

## Workflow

1. Resolve the PR (URL, branch, or current). Run `ck_git_diff` and `ck_git_status`.
2. Run `ck_validate` on the diff. Resolve blocked findings first — reviewability is secondary to correctness.
3. Diagnose reviewability issues against [checklist](references/pr-checklist.md):
   - Noisy/mixed-intent commit history
   - Missing or stale PR description
   - Unrelated changes mixed in
   - Mechanical changes mixed with logic
   - Missing test coverage for core change
   - Unclear reviewer entry points
4. Record issues as `ck_finding` (category `reviewability`, severity `medium`/`low`).
5. Submit plan via `ck_review_submit` (review_type: `plan`) describing what will change. **Wait for approval** before rewriting history or force-pushing.
6. Apply approved improvements. After any history rewrite, verify tree hash unchanged:
   ```
   ORIGINAL_TREE=$(git rev-parse origin/<branch>^{tree})
   # ... rewrite ...
   # Tree must match
   ```
7. Update PR description with: TL;DR, core files (3-7), mechanical files, risk callouts, context links.

## Guardrails

- Never hide behavior changes inside cleanup
- Never force-push without `ck_review_submit` approval
- If PR too large to review, recommend splitting instead of polishing
- If `ck_validate` blocked, fix those first

## Output

- `ck_finding` records for reviewability issues
- `ck_review_submit` plan (approved)
- Updated PR description with reviewer guidance
- Verified tree identity after any history changes