github-review - SKILL.md Agent Skill

name: github-review description: "Review a GitHub pull request by collecting PR context, analyzing risks, and publishing one structured review."

GitHub Review Skill

Summary

Use this skill when you need to review a pull request, identify the highest-signal findings, and publish one structured GitHub review.

When To Use

Reviewing an open pull request for correctness, regressions, or safety issues
Publishing a review summary plus optional inline comments
Working directly from raw GitHub CLI and API data

Do Not Use

Implementing fixes on the PR branch
Opening a new PR from an issue
Project-wide prioritization or PM analysis

Prerequisites

gh CLI authentication is required.
GITHUB_TOKEN/GH_TOKEN needs permissions to read PR data and publish reviews/comments.

Runtime Paths

GITHUB_OUTPUT_DIR: output artifacts directory (caller-provided preferred; otherwise temp dir).
GITHUB_CONTEXT_DIR: context directory (default ${GITHUB_OUTPUT_DIR}/github-context).

Inputs (Manifest-First)

Preferred input when already available:

${GITHUB_CONTEXT_DIR}/manifest.json

Optional inputs:

Any context artifact listed as status=present in manifest.json.
Runtime-provided repository or path-specific review instructions.

If no manifest is provided, collect PR context directly with gh:

gh pr view <pr_number> --repo <owner/repo> --json number,title,body,state,url,baseRefName,headRefName,headRefOid,author,createdAt,updatedAt,mergeable,reviews,changedFiles,additions,deletions
gh pr view <pr_number> --repo <owner/repo> --json files
gh pr diff <pr_number> --repo <owner/repo>
gh api repos/<owner>/<repo>/issues/<pr_number>/comments --paginate
gh api graphql -f query='
  query($owner:String!, $repo:String!, $number:Int!) {
    repository(owner:$owner, name:$repo) {
      pullRequest(number:$number) {
        reviewThreads(first:100) {
          nodes {
            isResolved
            comments(first:100) {
              nodes { id body path line author { login } }
            }
          }
        }
      }
    }
  }' -F owner=<owner> -F repo=<repo> -F number=<pr_number>

This skill must not assume fixed context filenames. Use manifest.artifacts[] (id, path, status, description) to determine available context. When the runtime provides repository or path-specific review instructions, treat them as authoritative project context for this review. Do not discover, parse, or match path-specific instruction files inside this skill; that context assembly belongs to the caller/runtime.

Workflow

1. Collect context

If ${GITHUB_CONTEXT_DIR}/manifest.json exists, use it.
Otherwise, collect PR metadata, files, diff, comments, and review-thread context directly with gh.
Record which runtime-provided repository/path instructions are available. If the runtime exposes instruction names, paths, or match metadata, preserve that metadata in the execution summary.

2. Perform review

Generate:

${GITHUB_OUTPUT_DIR}/review.md
${GITHUB_OUTPUT_DIR}/review.json
${GITHUB_OUTPUT_DIR}/summary.md
${GITHUB_OUTPUT_DIR}/review-publish.json after a successful publish, or when publishing is skipped because an equivalent same-head review/comment already exists
Optional ${GITHUB_OUTPUT_DIR}/manifest.json (execution metadata)

3. Publish review

Use gh api with a JSON payload file:

gh api repos/<owner>/<repo>/pulls/<pr_number>/reviews -X POST --input <review-payload.json>

Review Standards

Scope and priority

Review focus order:

Correctness bugs
Security/safety issues
Performance/scalability risks
API compatibility and error handling
High-impact maintainability issues

Incremental-first

Prioritize newly introduced changes (new commits and new diff hunks).
Expand scope only when needed to validate correctness or safety.

Runtime-provided project context

Apply any runtime-provided repository or path-specific review instructions to matching files as binding project context.
If runtime-provided instructions conflict with generic review heuristics, follow the repository/path instruction unless it would hide a correctness, security, or safety issue.
If instruction metadata is unavailable, do not infer that no project-specific instructions exist; state the coverage limitation in summary.md.

Line-level risk scan

Review each changed file and materially changed hunk before deciding there are no findings. For every relevant hunk, explicitly consider:

control-flow and lifecycle regressions, including missed wake/sleep, retry, cancellation, cleanup, or state-transition paths
trust-boundary or provenance mistakes, including implicit trust elevation, mixed operator/external input, missing authorization checks, or secret leaks
error handling gaps, including swallowed errors, ambiguous retries, unchecked fallbacks, panics, unwrap/expect, or misleading success states
data-shape and compatibility changes, including schema drift, missing migration behavior, broken serialization, or public contract changes
concurrency and ordering risks, including races, stale reads, duplicate side effects, non-idempotent publishes, or hidden background work
resource and performance risks, including unbounded loops, large context expansion, unnecessary network calls, or avoidable memory growth
test and observability gaps that would let a high-impact regression pass silently

Use this scan to find concrete issues, not to produce checklist noise. Only publish findings that are supported by the diff or directly relevant surrounding code.

Historical deduplication

Check existing review threads/comments before raising findings.
Do not repeat already-raised issues unless there is new evidence or changed impact.
If re-raising, explain the delta briefly.

Keep signal high

Avoid low-value style nitpicks unless they affect behavior/maintainability.
Keep feedback concise, specific, and actionable.
Prefer fewer high-impact findings over exhaustive noise.

Output Contract

`review.md`

Human-readable review summary containing:

conclusion-first summary
key findings ordered by severity
actionable recommendations

`review.json`

Structured inline findings:

[
  {
    "path": "path/to/file.go",
    "line": 42,
    "severity": "error|warn|nit",
    "message": "Issue description",
    "suggestion": "Optional concrete fix"
  }
]

Severity semantics:

error: must-fix before merge
warn: should-fix
nit: optional improvement

`summary.md`

Short execution summary:

reviewed ref/head
context coverage summary from manifest
repository/path instruction coverage, including instruction metadata when provided by the runtime
number of findings and publish outcome
explicit degradation/failure reason when context is insufficient

Degradation Rules

If core review artifacts are missing (for example pr_metadata, diff and files both unavailable), do not fabricate certainty.
If runtime-provided instruction metadata is expected but unavailable, continue the review using the available PR context, but record that limitation in summary.md.
Either:
- produce summary-only review with explicit limitations and no inline comments, or
- fail with clear reason in summary.md.

Publishing Guardrails

Publish at most one review per execution round.
Treat review/comment publishing as a single-shot external side effect: choose one publish surface, either one PR review or one PR comment, not both.
Capture the target PR headRefOid before publishing and use it as the deduplication key.
Before any publish or retry, check existing reviews/comments by Holon or the current GitHub actor for the same head SHA. If an equivalent review/comment already exists, skip publishing and record the existing URL/status.
A successful primary publish is terminal; immediately write the publish result to ${GITHUB_OUTPUT_DIR}/review-publish.json and do not run alternate publish paths.
Before fallback publish, require both conditions: no local review-publish.json success marker exists, and no equivalent Holon review or comment exists for the same head SHA.
If a publish command result is ambiguous, verify existing reviews/comments for the same head SHA before retrying. Do not retry blindly.

Configuration

DRY_RUN=true: preview only.
MAX_INLINE=N: cap inline comments.
POST_EMPTY=true: allow posting empty review.