code-review

name	code-review
description	Execute expert-level code reviews, dissecting codebases and Pull Requests (PRs) with surgical precision to identify logical flaws, architectural drift, performance bottlenecks, and security vulnerabilities before they merge. You MUST load this skill when reviewing code or Pull Requests.
license	MIT

Skill: code-review

Execute expert-level code reviews, dissecting codebases and Pull Requests (PRs) with surgical precision to identify logical flaws, architectural drift, performance bottlenecks, and security vulnerabilities before they merge.

WHEN TO USE

• When explicitly asked to review, audit, or verify a Pull Request before it merges.
• To analyze a specific code snippet or file for security vulnerabilities, architectural drift, or logical flaws.
• When performing a final verification check as part of a larger agentic task.

WHEN NOT TO USE

• When the objective is simply to format code or fix syntax errors (use coding-standard-writer or linters).
• If the PR is a trivial documentation update (use docs-review instead).
• When tasked with writing new features from scratch.

Common Pitfalls

• Bypassing the Tests: Jumping straight into the implementation code without checking if the accompanying tests actually assert the correct behavior.
• Nitpicking the Trivial: Leaving dozens of comments about trailing whitespace or variable naming conventions while completely missing a critical SQL injection vulnerability.
• Vague Suggestions: Pointing out that a function is "too complex" without actually providing a concrete, refactored snippet to solve the problem.

Core Process

1. Review Tests First: Always analyze the tests before the implementation code; they reveal the true intent and coverage gaps.
2. Spec-First Alignment: Read the specification or task description thoroughly before beginning the code review.
3. Adversarial Self-Inquiry: Actively play devil's advocate against the proposed solutions. Probe for bugs, compliance risks, and hidden edge cases ("How could this break?").
4. Evaluate Dimensions:
   • Code Hygiene: Scan for trailing whitespace, temporary/debug statements (console.log, print, TODO, FIXME, debugger breakpoints), unintended files (.env, logs), syntax errors, and visible inconsistencies (e.g., duplicated code, undefined variables, unused imports, dead code).
   • Correctness & Robustness: Verify functional alignment (does the code actually do what it is described to do?), edge cases, logic integrity, and test efficacy.
   • Readability & Maintainability: Ensure self-documentation, convention adherence, flow simplicity, and logical organization.
   • Architecture & Design: Check pattern alignment, modular integrity, abstraction level, and dependency flow.
   • Zero-Trust Security: Validate boundaries, scrutinize for secrets, verify AuthZ/AuthN, and prevent injection.
   • High-Performance Engineering: Identify inefficient queries, unbounded loops, blocking synchronous operations, and UI/API bottlenecks.
   • Overengineering Detection: Flag premature optimizations, feature creep, over-abstraction, and testing extremism. Apply YAGNI (You Aren't Gonna Need It) aggressively.
   • Documentation Currency: Verify that the documentation is up to date. Ensure AGENTS.md, README.md, and other relevant docs accurately reflect the new changes.
5. Formulate Feedback: Prefix every comment with a clear priority label ([CRITICAL], [IMPORTANT], [SUGGESTION], [QUESTION], [PRAISE]). Provide a concrete resolution path for every issue raised.
6. Summarize Review: Output a summary containing Verdict (APPROVE or REQUEST CHANGES), Overview (1-2 sentences), and a Verification Story checklist (Tests reviewed, Build verified, Security checked).
7. External Repositories Check: When code contains references to external repositories, double-check them (use: , load skill).

Core Principles

• Review-Only Enforcement: Operate strictly in review-only mode. Do not modify files, create commits, or execute test suites/build scripts directly. Base analysis solely on reading the code and static analysis.
• Problem + Resolution Guidance: For every issue raised, describe both the failure mode and a concrete resolution path (e.g., exact refactor direction, validation rule, test addition, or replacement snippet).
• Least Privilege Principle: Veto any PR that unnecessarily expands the attack surface, requests excessive permissions, or uses overly broad scopes.
• Information Hiding: Scrutinize whether the PR leaks internal implementation details across clear logical boundaries. Demand encapsulation.
• Zero-Scaffolding Tone: Formulate review feedback in bold, declarative, and respectful technical language. Focus objectively on the code, discarding personal tone or redundant exposition.

Best Practices

Enforce these code quality standards during the review:

• Functions do one thing.
• Names are descriptive and intention-revealing.
• Error handling is explicit.
• Tests cover the change.
• Keep functions small and focused.
• Match existing patterns in the codebase.

Success Indicators

These principles are working if you see:

• Fewer unnecessary changes in diffs.
• Fewer rewrites due to overcomplication.
• Clarifying questions come before implementation (not after mistakes).
• Clean, minimal PRs without drive-by refactoring.
• Tests that document expected behavior.

Commands / Usage Patterns

While the workflow is managed by github-pr-review, this skill focuses on analyzing the diff and formulating feedback.

• Check for hygiene issues in diff:

  # Check for trailing whitespace and conflict markers
  git diff <base>...HEAD --check
  
  # Check for debug statements and markers
  git diff <base>...HEAD | grep -E "console\.log|debugger|print\(|TODO|FIXME|<<<<<<<|>>>>>>>"
  

• Post a structured review comment:

  gh pr review <number> --comment -b "$(cat <<EOF
  ## Code Review Summary
  **Verdict**: APPROVE | REQUEST CHANGES
  **Overview**: <1-2 sentences>
  
  ### Verification Story
  - [ ] Tests reviewed
  - [ ] Build verified
  - [ ] Security checked
  EOF
  )"
  

What to Avoid

• Approving PRs that contain [CRITICAL] issues (security vulnerabilities, data loss risks, or broken functionality).
• Providing a problem without hinting at a solution vector. NEVER point out a [CRITICAL] or [IMPORTANT] flaw without proposing a concise, high-fidelity alternative snippet or architectural pivot.
• Quoting massive unchanged blocks in feedback. Highlight only the segments of code requiring attention.
• Overlooking missing tests or shallow coverage.
• Bypassing validation boundaries, leaking state, or hardcoding credentials.
• Magic numbers or hardcoded strings without named constants.
• Commented-out code left in the diff.
• Adding dependencies without justification.

Limitations

• This skill relies on static analysis and reading code; it does not execute the code to verify runtime behavior dynamically.

Related Skills

• critical-thinking: You MUST load this skill when applying deep analytical reasoning to complex changes.
• testing: Load this skill when you need to design or suggest new tests to cover identified gaps.
• github-pr: You MUST load this skill when working with changes associated with a pull request.
• github-pr-review: You MUST load this skill when reviewing, auditing, or verifying a GitHub Pull Request.
• gh-pr: You MUST load this skill when working with the gh pr command.