Skip to main content
skill CX Codex

github-deep-review — Claude Code skill: bug analysis and PR review with evidence

github-deep-review — a skill for in-depth GitHub issue and PR review. Reads code, traces the root cause, proposes the best fix, and identifies what must be verified before merge.

MIT 275 installs ★ 7,554 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add steipete/agent-scripts --skill github-deep-review -a claude-code
Open on GitHub

What github-deep-review does

github-deep-review teaches an agent to analyze GitHub issues and pull requests like an experienced reviewer: code first, conclusions second. Instead of generic remarks, the skill demands proof — git history, test coverage, CI results, behavior on the current main branch. The agent gathers author context, follows the call chain from entry point through validation and routing to the persistence boundary, and checks dependency contracts from their documentation rather than assumptions.

For each bug, the skill requires answers to: what breaks, where in the code, who introduced it and when (verified through raw commits, not dates alone), whether the proposed fix is optimal, and if a larger refactor would prevent similar bugs. For PRs, it identifies specific correctness issues by file and line, lists the evidence checked, and flags remaining risks. Output is a structured report with code references and commit links, without vague suggestions.

Installation requires the gh CLI for querying GitHub and local repository access for history analysis. The skill runs on Claude Code, Codex, Cursor, GitHub Copilot, and Gemini CLI.

What it helps with

  • pinpoint what breaks in a bug and locate it in the codebase
  • trace the actual root cause through commit history instead of speculation
  • determine whether a proposed fix is the best option available
  • review a PR for correctness with references to specific code lines
  • spot whether a larger refactor would eliminate a whole class of bugs

Example prompts for the agent

  • Review PR #42 in our repo: what breaks, where is the root cause, what's the best fix?
  • Analyze issue #15 on GitHub, reproduce the problem, and suggest a fix with a test
  • Check this commit: who introduced it, why is it a regression, and how should we fix it?

How to install github-deep-review

1Skills CLI (Vercel)

npx skills add steipete/agent-scripts --skill github-deep-review -a claude-code

2Manually: put the files in place

~/.claude/skills/github-deep-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/github-deep-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about github-deep-review

How do I install github-deep-review in Claude Code?

Run npx skills add steipete/agent-scripts --skill github-deep-review -a claude-code. After installation, open ~/.claude/skills/github-deep-review/SKILL.md for full documentation.

What does github-deep-review do?

The skill trains an agent to review GitHub issues and PRs like a senior developer: follow the call chain through code, find the real bug source in commit history, evaluate fix quality, and list remaining risks with concrete evidence.

Which platforms support this skill?

github-deep-review works on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. It requires local gh CLI access for GitHub queries and repository access for history analysis.

Source text

SKILL.md · MIT
---
name: github-deep-review
description: "GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first."
---

# GitHub Deep Review

Review like Peter: high-confidence, evidence-first, code-aware, and willing to say "not proven" when the trail is weak. The goal is not a generic summary. The goal is to understand the bug class, find the real cause if possible, decide the best fix after reading enough code, and call out whether a larger refactor would improve the design.

## Start

Use `gh`, not web browsing, for GitHub refs:

```bash
gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch
```

For PRs, collect author context by default unless the author is Peter (`steipete` or an obvious Peter-owned account). Use the local workflow in `~/Projects/agent-scripts/skills/github-author-context/SKILL.md` and include a short `Author context:` block near the top of the review when the author is not Peter.
After merge/rejection/close/review, use that same author-context workflow to append a contributor note only when the interaction creates durable future-review signal.

For repo-local review, also inspect:

```bash
git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<key symbol/error/config/endpoint>"
```

If the repo has local instructions, issue/PR skills, docs lists, test guidance, or maintainer runbooks, read those before deciding.

## Review Contract

Always answer these, explicitly:

- URL/ref: issue or PR number and affected surface.
- What is the bug or behavior being fixed?
- Can we identify the root cause? If yes, where in code and why. If no, what evidence is missing.
- For regressions, who/what introduced it and when? Include commit/PR provenance when traceable by bounded history; say unknown instead of guessing.
- Is the current/proposed fix the best possible fix after reading adjacent code?
- Would a bigger refactor improve correctness, clarity, or future maintainability?
- What proof exists: tests, live repro, CI checks, docs, dependency docs/source, shipped/current behavior.
- What remains risky or unverified.

## Code Reading Depth

Read past the first touched file. Follow the real call path:

- entrypoint -> validation/parsing -> routing/dispatch -> owner module -> shared helper -> persistence/network/runtime boundary
- config/schema/docs -> runtime usage -> doctor/migration/fix path
- provider/channel/plugin owner code -> generic core seam, only if multiple owners need it
- tests around the touched surface plus adjacent regression tests

When behavior depends on a dependency, read the upstream docs/source/types or current package contract before assuming.

Prefer current source and executable proof over issue comments. Treat stale comments, old CI, and old release behavior as hints until rechecked.

## Provenance

For bug/regression reviews, include a compact `Provenance:` answer when feasible:

- Use `git log -S/-G`, `git blame`, and linked PRs/issues to locate candidates, not prove introduction. Before saying `introduced by`, inspect raw parents with `git --no-replace-objects cat-file -p <sha>` and verify that `git --no-replace-objects diff --no-ext-diff --no-textconv <raw-parent> <sha> -- <path>` changed the implicated behavior, using tests/repro when feasible. A genuine root needs raw-header proof that it has no parents.
- Blame `^sha`, porcelain `boundary`, and shallow/grafted history alone are not introduction proof. `--root` can hide boundary markers; `git show` and `rev-list --parents` can disguise a shallow boundary as a root. An available raw parent permits explicit comparison even at a shallow boundary; missing parents or an unverifiable patch require `unknown` with the gap, not inference from a subject, date, or author.
- Separate code author, introducing PR author, merger, committer, automation trigger, and current PR author. Verify identities and triggers from explicit metadata/events; a role is not proof of causation, and an unverified identity stays unknown.
- Use `made visible by` only for a verified trigger and `carried forward by` only for verified preexisting behavior. Apply the same evidence bar to summaries and owner hints, not just a `Provenance:` field. Include confidence: `clear`, `likely`, or `unknown`.
- For features, docs, and refactors, write `N/A`; for untraceable bugs, report `unknown` with the missing evidence. Missing provenance does not invalidate an independently proven bug.

## Fix Quality Bar

Good fixes usually:

- live at the ownership boundary where the bug belongs
- preserve public/backward-compatible behavior unless the issue is about retiring it
- add a regression test at the smallest meaningful seam
- avoid broad special cases, hidden migrations, semantic sentinels, and provider/channel IDs in generic core
- update docs/changelog when user-visible behavior changes
- fail clearly in runtime paths and repair through doctor/migration paths when that is the established contract

Call out when a fix is only symptom-level. If a slightly larger refactor makes the invariant obvious and reduces future bugs, recommend it. If the refactor widens risk without improving the bug class, say so.

## PR Review Shape

Lead with findings when reviewing a PR. Findings need file/line/symbol references and a concrete failure mode. Avoid vague "consider" comments.

If no blocking issues:

- say no blocking correctness issues found
- list the strongest proof checked
- name residual risk/test gaps
- answer whether the design is the best available shape

Do not approve, comment, close, merge, push, or land unless the user asked for that action.

## Issue Review Shape

For bugs/issues:

1. Reconstruct the reporter's scenario and affected version/surface.
2. Check whether current `main` already fixes it.
3. Reproduce or create a minimal local/live proof when feasible.
4. If clear, identify root cause and proposed fix.
5. If solved on `main`, only comment/close when the user asks; include proof and the canonical commit/PR if known.

If reproduction is not feasible, say exactly what blocks it and what evidence would make the decision reliable.

## Output Template

Use this shape when the user asks "what is this about", "is this the best fix", or "what did we fix":

```text
Ref: #123 / PR #456
Surface: <runtime/CLI/provider/channel/docs>

Bug: <one or two sentences>
Cause: <code path + confidence>
Provenance: <introduced/made visible/carried forward by commit/PR/date, or N/A/unknown>
Best fix: <what should change and why>
Refactor: <yes/no, specific shape>
Proof: <tests/live/CI/source/dependency docs>
Risk: <remaining uncertainty>
```

Keep it concise, but do not skip the cause/fix/refactor/proof decision.

© steipete · MIT · steipete/agent-scripts

Similar skills

All skills for Code review and refactoring →

From the same set20

The whole set →
create-cli create-cli drafts human-friendly CLI specifications with argument tables, exit codes, and output contracts based on clig.dev guidelines before writing code. CX Codex +1 508installs markdown-converter markdown-converter converts documents, spreadsheets, PDF, media, and structured data into Markdown via uvx without manual parser setup. CX Codex +1 346installs codex-first codex-first routes tasks between Claude and Codex workers. Claude handles specifications and judgment while Codex runs implementations and automated reviews. CX Codex +1 288installs browser-use browser-use — a skill to control your real Chrome profile with saved logins and extensions. Routes through the Codex plugin when available, then OpenClaw extension over mcporter, and falls back to direct DevTools attachment if needed. CX Codex +1 278installs native-app-performance CLI skill for analyzing native app performance via xctrace and Time Profiler. Records execution traces, extracts samples, symbolicates stack frames, and identifies bottlenecks without opening Instruments. CX Codex +1 251installs instruments-profiling The instruments-profiling skill guides macOS and iOS profiling with Instruments and xctrace, from trace capture to stack export. Use it when a native app has a slow path. CX Codex +1 242installs ssh-doctor ssh-doctor troubleshoots macOS SSH failures, including pre-auth disconnections, stale sshd sessions, and Remote Login misconfigurations. CX Codex +1 239installs domain-dns-ops The domain-dns-ops skill guides domain, Cloudflare zone, and redirect work. Use it when setting up a domain and checking DNS or HTTPS behavior. CX Codex +1 192installs

Project sponsors

Companies that keep this analytics open