agentleFS
Sign inStart free
jaydubya818jaydubya818/MissionControl/skills/make-pr-easy-to-review/SKILL.md

make-pr-easy-to-review

Skill2 starsChanged 8 months agoMITView on GitHub

Use when a correct pull request needs clearer history, description, or reviewer guidance.

We split this skill into the rules it gives an agent

9 rules. 9 are common, 0 are distinctive, and 0 are very specific to this project.

  • 9

    Common

    Most of the 6 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

    Only rewrite history when the user asks for it or agrees to the plan.

    line 29
  2. Common:

    After rewriting, verify content identity:

    line 45
  3. Common:

    Do not push if the tree changed unintentionally.

    line 53
  4. Common:

    When code behavior should stay untouched, prefer PR description and review notes:

    line 57
  5. Common:

    Add a TL;DR that matches the actual diff.

    line 59
  6. Common:

    Call out risky behavior changes, migration order, rollout plan, and test coverage.

    line 61
  7. Common:

    Never hide meaningful behavior changes inside "cleanup".

    line 66
  8. Common:

    Do not bypass hooks unless the user explicitly asks.

    line 67
  9. Common:

    If the PR is too large to make reviewable with notes, recommend splitting instead of polishing around the problem.

    line 68

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Make PR Easy to Review

Prepare a PR so a reviewer can quickly understand the intent, important files, and risk. The default goal is reviewability without behavior changes.

Workflow

  1. Resolve the target PR from the user-provided URL or current branch.
  2. Inspect commits, diff size, changed paths, generated files, and PR description.
  3. Identify reviewability issues: noisy commits, stale description, unrelated changes, mixed mechanical and logic changes, missing tests, or unclear reviewer entry points.
  4. Propose a plan before rewriting history or force-pushing.
  5. Apply safe improvements, then verify the tree or diff still matches the intended code.

History Cleanup

Only rewrite history when the user asks for it or agrees to the plan. Before rewriting:

gh pr view <PR> --json title,headRefName,baseRefName,state,commits
git fetch origin <headRefName> <baseRefName>
ORIGINAL_TREE=$(git rev-parse origin/<headRefName>^{tree})

Good commit groupings usually follow dependency order:

  1. Schema/storage or generated API definitions.
  2. Core logic.
  3. Wiring and integration.
  4. UI or surface behavior.
  5. Tests.

After rewriting, verify content identity:

echo "Original tree: $ORIGINAL_TREE"
echo "Current tree:  $(git rev-parse HEAD^{tree})"
git diff origin/<headRefName> --stat

Do not push if the tree changed unintentionally.

Reviewer Guidance

When code behavior should stay untouched, prefer PR description and review notes:

  • Add a TL;DR that matches the actual diff.
  • Separate core files from generated or mechanical files.
  • Call out risky behavior changes, migration order, rollout plan, and test coverage.
  • Link issue trackers, dashboards, or design docs when they explain intent.

Guardrails

  • Never hide meaningful behavior changes inside "cleanup".
  • Do not bypass hooks unless the user explicitly asks.
  • If the PR is too large to make reviewable with notes, recommend splitting instead of polishing around the problem.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free