gh-review-suggestions

What this skill does

# GH Review Suggestions

Review a GitHub PR and post inline comments only when the suggestion is safe,
specific, and directly applyable.

## Contract

Inputs:

- PR URL or number
- Optional target files, review scope, and severity threshold

Outputs:

- Findings grouped by severity
- Inline suggestion draft bodies
- Posted review comment URLs after approval

Creates/Modifies:

- Does not modify local files by default
- May post GitHub review comments after approval

External Side Effects:

- Reads PR metadata and diffs
- Posts GitHub PR review comments only after approval

Confirmation Required:

- Before posting inline comments
- Before submitting an approve/request-changes review
- Before checking out or modifying the PR branch

Delegates To:

- `code-review` for local bug-focused review
- `gh-address-comments` when addressing existing review feedback
- `gh-fix-ci` when failing checks explain the review finding

## Workflow

1. Verify context:

   ```bash
   gh auth status -h github.com
   gh pr view <pr> --json number,title,url,headRefOid,commits,files,reviewDecision
   gh pr diff <pr> > /tmp/pr.diff
   ```

2. Review changed files, not the whole repository. Focus on:
   - Bugs and behavioral regressions
   - Security and data-isolation failures
   - Broken tests or missing coverage for changed behavior
   - Simple code corrections that GitHub suggestions can apply cleanly

3. Use inline suggestions only for mechanical, local changes:

   ````markdown
   Explain why this concrete change is needed.

   ```suggestion
   replacement code
   ```
   ````

   Use normal comments for architecture, product, design, or multi-file changes.

4. Validate the target line is in the PR diff:

   ```bash
   node skills/gh-review-suggestions/scripts/diff-line-position.mjs \
     --diff /tmp/pr.diff \
     --path src/example.ts \
     --line 42
   ```

5. Draft comments and get approval before posting.

6. Prefer modern `line`/`side` API fields when posting comments:

   ```bash
   COMMIT_ID="$(gh pr view <pr> --json commits --jq '.commits[-1].oid')"
   gh api \
     --method POST \
     /repos/<owner>/<repo>/pulls/<pr>/comments \
     -f body="$(cat /tmp/comment.md)" \
     -f commit_id="$COMMIT_ID" \
     -f path="src/example.ts" \
     -F line=42 \
     -f side=RIGHT
   ```

   If targeting an older GitHub Enterprise instance that requires `position`,
   use the helper output's `position` field.

7. Summarize what was posted:
   - Finding severity
   - File and line
   - Comment URL if returned
   - Any findings intentionally left as summary-only comments

## Rules

- Do not post style-only comments unless the repo has an explicit style rule.
- Do not post overlapping suggestions on the same lines.
- Do not suggest generated lockfile or bundle changes unless the generated file
  is the source of truth.
- Do not request changes for speculative concerns. Ask a question or leave a
  non-blocking comment instead.
- If there are more than five comments, group low-priority notes into one
  summary comment to avoid review noise.