github-pr-comments

Files (1)

• SKILL.md

SKILL.md (first lines)

# GitHub PR Comments

Use this skill to turn reviewed findings into useful GitHub comments. It covers drafting, formatting, verification, and authorized posting
it does not replace code review. Load `review` for the review itself and `github` for GitHub CLI rules

## Core Rules

- Use `gh` only for GitHub operations. Never use GitHub MCP
- Recheck the PR head immediately before quoting or posting comments
- Verify every finding from source, diff, checks, docs, prior comments, and the selected proof method
- Use the selected proof method. Do not run a live, external, credentialed, or effectful probe until its approval gate allows it. If a meaningful live check does not run, name the strongest non-live evidence and say what live behavior remains unchecked
- State assumptions. If a finding depends on one, ask it as a question
  - drop it when the assumption is weak or unverifiable
- Drop speculative "what if" nits unless the user explicitly asks for exhaustive hypotheticals
- Prioritize concrete, evidence-backed comments about simplification, design, architecture, structure, source-of-truth ownership, deduplication, typing boundaries, and existing-pattern reuse
- Other minor nits require the user's explicit selection before posting
- Keep language casual, direct, and code-focused. No filler, praise padding, or performative politeness

These rules combine GitHub review conventions with the user's preference for concise, evidence-backed comments

## Preflight Checklist

Before drafting comments:
1. Load `github` and `review` skills if not already loaded
2. Identify repo and PR number
3. Recheck PR metadata:

   ```bash
   gh pr view <PR> --json headRefOid,state,updatedAt,changedFiles,additions,deletions,title,url
   ```

4. Recheck checks when relevant:

   ```bash
   gh pr checks <PR>
   ```

5. Get the diff/patch for inline anchor validation:

   ```bash
   gh pr diff <PR> --patch > /tmp/pr-<PR>.diff
   ```

6. Read relevant current files at the reviewed head, not stale local assumptions. Use one of these read-only paths:

   ```bash
   # First compare local HEAD to the fetched PR headRefOid:
   LOCAL_HEAD=$(git rev-parse HEAD)
   test "$LOCAL_HEAD" = "<HEAD_SHA>"

   # Only if that equality check passes, local file reads are valid.
   # Otherwise read a file from the PR head without checkout:
   git show <HEAD_SHA>:path/to/file

   # Or, for remote-only review:
   gh api 'repos/<owner>/<repo>/contents/path/to/file?ref=<HEAD_SHA>' --jq .content | base64 -d
   ```

   If `git rev-parse HEAD` does not equal the fetched PR `headRefOid`, do not trust local file reads for PR-head evidence. Do not use `git checkout`, `git switch`, `git reset`, or other mutating git commands just to inspect PR contents

7. Read existing comments by default to avoid duplicate/noisy feedback:

   ```bash
   gh api --paginate 'repos/<owner>/<repo>/pulls/<PR>/comments?per_page=100'
   gh api --paginate 'repos/<owner>/<repo>/pulls/<PR>/reviews?per_page=100'
   gh api --paginate 'repos/<owner>/<repo>/issues/<PR>/comments?per_page=100'
   ```

   Skip this only when the user explicitly says duplicate checking is unnecessary

8. If the PR head changes while drafting, restart verification against the new head

## Finding Filter

Post only findings that pass all gates:
- **Evidence:** Direct source/diff/test/docs/CI evidence exists
- **Claim-bound proof:** The selected proof method directly supports the claim. If live proof did not run, name the strongest non-live evidence and the live behavior that remains unchecked
- **Impact:** The comment explains why it matters
- **Actionability:** The author can fix it, answer a focused question, or intentionally decline it
- **Scope:** The issue belongs to this PR, not unrelated old code
- **Signal:** The comment is worth the notification/noise cost. Architecture/design/simplification issues get higher priority than cosmetic or preference nits
- **No speculation:** The comment does not rely on an invented "what if" unless the risk is direct and realistic
- **Assumptions listed:** Any assumption is explicit, separated from evidence, and phrased as a question instead of a fact

Drop or downgrade:
- linter/style issues that automation should catch,
- personal taste without a repo pattern,
- minor non-architecture/non-design/non-simplification nits unless the user explicitly approves posting them,
- huge refactors not required for the current PR,
- generic architecture essays that can be split into specific comments,
- uncertain claims that cannot be verified
  - ask a question or mark as not 100% instead,
- claims whose selected proof method was skipped or replaced with weaker evidence without justification,
- assumption-led comments where the assumption is likely wrong, unimportant, or not worth asking about

## General vs Inline Placement

Use **inline comments** for:
- a concrete issue on a changed line,
- a local simplification/refactor at one spot,
- a type/API problem visible at a specific declaration,
- a test/doc issue anchored to a new/changed line

Use the **review body / general PR comment** for:
- cross-cutting architecture feedback,
- comments spanning multiple files,
- scope/product questions,
- findings whose exact best anchor is not changed/commentable,
- summary of verification and review rubric

Do not force an inline comment onto a bad line. If the anchor is not commentable in the diff, move it to the review body

## Comment Shape

Use this shape for each postable comment. Keep it concise but complete

```markdown
<casual opening sentence / focused question>

From OrestesK/pi, MIT.

More from OrestesK/pi