# Pr Self Review > Draft short, plainspoken notes in the author's voice that help reviewers understand non-obvious choices, boundaries, and preserved behavior in the author's own pull request or local diff. Use when the user asks to self-review, annotate, or add reviewer context to their PR or changes. Draft locally when no PR exists, and post approved notes as one GitHub review when a PR does exist. Do not use for reviewing someone else's PR, writing code comments, explaining code generally, or drafting a PR description. Never post without explicit approval. - Skill: `petekp/pr-self-review` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add petekp/pr-self-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/petekp/pr-self-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: petekp (https://skillmd.com/u/petekp) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/petekp/pr-self-review --- # PR self-review notes Read the diff as a reviewer and answer the few questions the code cannot answer for itself. Zero notes is a good result when the change is already clear. Most PRs need zero to three; larger or unusually subtle changes may need more. These are quick asides to a teammate, not documentation or a defense of the change. ## 1. Establish the target and authorship Default to the PR for the current branch. If the user names a PR number or URL, use that target and its repository for every command. ```bash gh pr view \ --json number,title,body,author,headRefName,headRefOid,state,url gh api user --jq .login ``` Add the PR number or URL after `view` when the user names a target. Pass `--repo ` when a numbered target belongs to a repository other than the current one. A full PR URL can be used directly. Record the PR URL, `owner/repo`, number, author, and `headRefOid`. Only write self-review notes when the signed-in account is the PR author and the PR is open. If the identities differ, stop rather than speaking as someone else. If no PR exists, continue in draft-only mode. Read the local branch diff against its intended base plus any staged and unstaged changes. Ask for the base only if it cannot be discovered safely. Explain that the notes cannot be posted until a PR exists. ## 2. Gather the context before choosing notes Read, in this order: 1. The user's stated intent, PR title and body, and any linked issue. 2. Existing PR discussion and review comments. 3. The whole diff, then the nearby code and tests for any candidate note. 4. Relevant history when the reason still is not clear. ```bash gh pr diff --repo gh api --paginate "repos///pulls//comments?per_page=100" gh api --paginate "repos///pulls//reviews?per_page=100" gh api --paginate "repos///issues//comments?per_page=100" ``` Check recent comments the author wrote or approved in the same repository when you need a voice sample: ```bash gh api "repos///pulls/comments?sort=created&direction=desc&per_page=100" \ --jq '.[] | select(.user.login == "") | {body,path,created_at}' ``` Copy the texture, never the wording. Prefer current user context over older examples. ## 3. Pick only useful notes Draft a note only when all of these are true: - A capable reviewer is likely to pause at this exact change. - The explanation helps them judge the change, not merely accept it. - The fact or reason is supported by the user, PR, code, tests, or history. - The PR body, code comments, and existing discussion do not already cover it. - It fits in one or two plain sentences. Good candidates include a surprising but verified choice, a deletion that may look like lost behavior, a narrow scope boundary, behavior that deliberately stays unchanged, or a known limitation the reviewer needs to judge now. Skip obvious edits, formatting, routine renames, and explanations that only repeat the diff. Never invent the author's intent. If the reason is unclear, state the visible effect without claiming intent, ask the user, or skip the note. A constraint that will still matter after merge may need a code comment. A PR note can help the current review, but it must not be the only place durable knowledge lives. Flag that separately; do not edit the code unless asked. ## 4. Write in the author's PR-comment voice Use recent same-repo comments as the strongest style evidence. For Pete, use this dedicated PR-comment register rather than importing the broader `write-as-pete` tics: - Start with the fact. Lowercase starts are normal when they match the nearby precedent; preserve official names and code casing. - Use one or two short sentences. A useful shape is what changes, followed by what stays or why it matters. - Prefer direct, pronoun-light wording. Use `we` only for a documented shared decision. Use `I` only when Pete explicitly stated a personal choice. - Use an exact code or domain term only when its exact meaning matters. Put code identifiers in backticks; prefer the plain feature name otherwise. - Use the least technical words that stay accurate. If the reviewer must decode two internal terms in one sentence, rewrite it around what changes, what stays, or what breaks. Avoid abstract labels such as "client contract," "runtime payload," and "availability sanitizer" when the concrete behavior is easier to say. - Keep punctuation quiet. Do not add hype, jokes, coined phrases, emojis, ellipses, or decorative em dashes to make the note sound more like Pete. - Avoid defensive phrases such as "on purpose" and "not a style slip." State the cause and effect, then let the reviewer judge it. - Avoid unsupported promises such as "easy to add later" or "one line to wire up." Read every draft together before presenting it. Remove repeated openings and sentence shapes. Delete anything that sounds like PR-body copy, a changelog, or a bot explaining the code. ### Shapes, not templates Never copy these sentences into a real review. Use them only to calibrate the level of detail, after verifying every claim. - Scope: "this size only applies to table selection. existing checkboxes keep their current size." - Preserved behavior: "the old action fields are gone. message and recipient checks still work as before." - Exact legacy input: "old links may still include `panel`. we ignore it here and clear it on the next navigation." - Plain translation: prefer "the picker still switches when the current option is unavailable" over "the availability sanitizer preserves the runtime invariant." ## 5. Show every public word and get approval Present every proposed public word. Include a review summary only when it adds a useful cross-file point that does not belong inline. When every useful point is inline, say the review summary is `none`; do not invent a status or count such as "left three notes inline." For each inline note, show the path, side, line, and body. If a claim needed investigation, show its basis outside the quoted comment so the user can verify it without making the public note denser. ```text Review summary none src/components/table.tsx:84 (RIGHT) "this size only applies to table selection. existing checkboxes keep their current size." Basis: the other checkbox callers still use the default size. ``` Wait for explicit approval before posting. Exact comment text paired with a clear instruction to post already counts as approval; do not ask twice. Post only the approved wording and anchors. If either changes, show the change and get approval again. ## 6. Publish and verify After approval, read [references/github-posting.md](references/github-posting.md) and follow it exactly. Post one review, then compare what GitHub stored with the approved summary, if any, and comments. ## Edge cases - If nothing earns a note, say so and post nothing. - Put a cross-file point in the review summary, not a separate PR comment. - When every useful point is inline, leave the review body empty. Never add a filler summary that only announces or counts the inline notes. - Check existing comments on every run, not only when the skill is re-run. - Edit an existing note in place rather than duplicating it, but show any new wording for approval first unless the user supplied the exact edit and told you to post it.