home / skills / tdhopper / dotfiles2.0 / reviewing-code

reviewing-code skill

safe

This skill helps review pull requests and diffs for completeness, tests, and performance, improving code quality and accountability.

npx playbooks add skill tdhopper/dotfiles2.0 --skill reviewing-code

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: reviewing-code
description: Review pull requests, branch changes, or code diffs. Triggers on "review this PR", "review my changes", "code review", "review branch", or GitHub PR URLs. Focuses on bugs, tests, complexity, and performance - not linting.
---

# Code Review

Focus on substantive issues: bugs, missing tests, complexity, performance, duplication, incomplete implementations. Skip linting concerns (formatting, imports, naming style).

## External Review (Optional)

Check for external reviewers and use if available. **Priority: Codex > Gemini**

```bash
command -v codex >/dev/null 2>&1 && echo "Codex available"
command -v gemini >/dev/null 2>&1 && echo "Gemini available"
```

**If Codex available:**
- Local branch: `codex --config model_reasoning_effort="high" review --base BASE_BRANCH`
- Remote PR: `gh pr diff NUMBER | codex review --config model_reasoning_effort="high" -`

**If only Gemini:** Pipe diff to gemini with review prompt.

## Workflow

1. **Get the diff**
   - PR: `gh pr view NUMBER --json title,body,files` then `gh pr diff NUMBER`
   - Branch: `git diff origin/master...HEAD`
   - Uncommitted: `git diff`

2. **Gather context** - Read PR description, commit messages, project CLAUDE.md

3. **Review each file** for:
   - **Completeness**: All code paths handled? Stubs left behind?
   - **Tests**: Added? Meaningful? Edge cases covered?
   - **Complexity**: Justified abstractions? Simpler alternatives?
   - **Performance**: Hot path regressions? Unbatched I/O?
   - **Duplication**: Similar code already exists? (`rg "pattern"`)

4. **Synthesize** external review (if used) with your findings. Consensus issues = high confidence.

## Output Format

```markdown
## Summary
[1-2 sentences]

## External Reviewer
[If used: Codex or Gemini]

## Key Findings

### Must Address
1. **[Issue]** (`file:line`) [Models]
   - Details
   - **Risk**: Why it matters

### Should Consider
2. **[Issue]** (`file:line`)
   - Details

### Minor Notes
- Observations

## Tests
[Coverage and quality assessment]

## Complexity
[Net impact on codebase complexity]
```

**Numbering**: Single sequence across all sections. Model attribution: `[Codex + Claude]`, `[Claude]`, etc.

## Scope

**In scope**: Logic errors, missing error handling, test gaps, performance regressions, unnecessary complexity, duplication, incomplete implementations, project guideline violations.

**Out of scope** (linters handle): Formatting, import order, naming style, type annotations, docstring format.

Overview

This skill helps you perform practical, high-value code reviews for pull requests, branch changes, or diffs. It focuses on substantive issues like correctness, tests, complexity, performance, duplication, and side effects rather than linting or style. Use it to get a clear, prioritized list of problems and suggested fixes you can act on quickly.

How this skill works

The skill inspects diffs from a PR URL, current branch, or uncommitted changes and evaluates each modified file for completeness, error handling, test coverage, performance, and duplication. It can optionally run external analysis tools (if available) and synthesize their output into a single, prioritized review. The output highlights must-fix bugs, recommended improvements, and minor notes with clear file/line pointers and risk explanations.

When to use it

Before merging a pull request to catch logical bugs and missing tests
When you want an objective assessment of test coverage and edge cases
To evaluate the complexity impact of a proposed change
When performance-sensitive code or hot paths are modified
If you suspect duplicated logic or unintended side effects

Best practices

Provide the PR description or commit messages so intent is clear
Run the review on the full diff (not individual hunks) to avoid missing context
Prioritize fixes that multiple tools or reviewers agree on
Focus comments on behavior, tests, and risks—not formatting
If unsure about intent, ask a clarifying question before requesting changes

Example use cases

Reviewing a GitHub PR URL to find missing error handling and test gaps
Assessing a feature branch for unnecessary new abstractions or complexity
Checking a change that touches hot loops or I/O code for regressions
Reviewing uncommitted changes locally to decide whether to add tests
Synthesizing findings from multiple analysis tools into a single action list

FAQ

Will this skill fix style and lint issues?

No. The skill intentionally skips formatting and style concerns because linters and CI should handle those.

Can it run other analysis tools automatically?

Yes, if supported tools are installed it runs them and synthesizes their findings; otherwise it falls back to the core review logic.