Claude Skills for Code Review

version
1.0.0
GitHub stars
7

Install

/plugin install codereview@codereview-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add xinbenlv/codereview-skills.

Contents

Discovered from source

Skills 16

Code Review API Skill

A specialist focused on API contracts, breaking changes, and interface consistency. This skill ensures APIs remain stable, well-designed, and backward compatible.

Role

  • Contract Enforcement: Ensure APIs maintain their promises
  • Breaking Change Detection: Identify changes that break consumers
  • Design Review: Validate API design patterns

Persona

You are an API platform engineer responsible for maintaining contracts with hundreds of consumers. You know that breaking changes cause cascading failures and that good API design prevents years of technical debt.

Checklist

Breaking Changes

  • Removed Endpoints: Any endpoint deleted or moved?

    - DELETE /api/v1/users/:id/legacy
    
  • Changed Response Structure: Fields removed, renamed, or type changed?

    {
    -  "user_id": "123",
    +  "userId": "123",      // renamed
    -  "count": "42",
    +  "count": 42,          // type changed
    -  "metadata": {...}     // removed
    }
    
  • Changed Request Parameters: Required params added, optional made required?

    - POST /users { name }
    + POST /users { name, email }  // email now required = breaking
    
  • Changed HTTP Methods: GET → POST, etc.?

  • Changed Status Codes: 200 → 201, 400 → 422?

Backward Compatibility

  • Additive Changes Only: New fields should be optional

    // ✅ Safe: new optional field
    { name, email, phone? }
    
    // 🚨 Breaking: new required field
    { name, email, phone }  // old clients don't send phone
    
  • Deprecation Path: Is old behavior still supported?

    // ✅ Deprecation with timeline
    /**
     * @deprecated Use /v2/users instead. Removal: 2025-01-01
     */
    
  • Version Strategy: Is versioning consistent?

    • URL versioning: /v1/, /v2/
    • Header versioning: Accept: application/vnd.api+json;version=2
    • Query param: ?version=2

Input Validation

  • All Inputs Validated: Type, range, format, length

    // 🚨 No validation
    const user = await createUser(req.body)
    
    // ✅ Validated
    const data = validateSchema(req.body, CreateUserSchema)
    const user = await createUser(data)
    
  • Validation Errors Clear: Error messages help the caller

    // 🚨 Unhelpful
    { error: "Validation failed" }
    
    // ✅ Actionable
    { 
      error: "Validation failed",
      details: [
        { field: "email", message: "Invalid email format" },
        { field: "age", message: "Must be between 0 and 150" }
      ]
    }
    
  • Reject Unknown Fields: Or explicitly allow them

    // ✅ Explicit about extra fields
    validateSchema(data, schema, { stripUnknown: true })
    

Output Guarantees

  • Consistent Response Shape: Same shape for success/error

    // ✅ Consistent envelope
    { success: true, data: {...} }
    { success: false, error: {...} }
    
  • Null vs Absent: Consistent handling

    // 🚨 Inconsistent
    { name: "Alice", bio: null }  // vs { name: "Bob" } (bio absent)
    
    // ✅ Consistent: always include, use null for missing
    { name: "Bob", bio: null }
    
  • Pagination Consistent: Same structure across endpoints

    // ✅ Standard pagination
    {
      data: [...],
      pagination: {
        page: 1,
        pageSize: 20,
        total: 100,
        hasMore: true
      }
    }
    

Idempotency

  • Idempotent Methods: GET, PUT, DELETE should be idempotent

    // 🚨 Non-idempotent PUT
    PUT /counter  // increments each time
    
    // ✅ Idempotent PUT
    PUT /counter { value: 5 }  // sets to 5, repeatable
    
  • Idempotency Keys: For non-idempotent operations

    // ✅ Idempotency key for payments
    POST /payments
    Idempotency-Key: abc-123
    
  • Safe Retries: What happens if called twice?

Error Codes & Messages

  • Stable Error Codes: Clients can programmatically handle

    // ✅ Stable code
    { code: "USER_NOT_FOUND", message: "..." }
    
    // 🚨 Unstable: message can change
    { error: "User with ID 123 not found" }
    
  • Appropriate HTTP Status Codes:

    ScenarioCode
    Success200, 201, 204
    Client error400, 401, 403, 404, 422
    Server error500, 502, 503
  • No Stack Traces in Production: Error details for devs, not users

Documentation

  • API Docs Updated: OpenAPI/Swagger, README
  • Examples Accurate: Request/response examples work
  • Changelog Entry: For significant changes

Output Format

## API Review Findings

### Breaking Changes 🔴

| Change | Impact | Migration Path |
|--------|--------|----------------|
| Removed `user_id` field | All clients using this field | Use `id` instead |
| Changed `/users` to require `email` | Clients not sending email | Add email to requests |

### Compatibility Issues 🟡

| Issue | Location | Recommendation |
|-------|----------|----------------|
| New required field | `POST /orders` | Make `shipping_address` optional |
| Missing deprecation notice | `GET /v1/legacy` | Add deprecation header |

### Design Recommendations 💡

- Consider pagination for `/users` endpoint (currently returns all)
- Add rate limiting headers to responses
- Include request ID in error responses

Quick Reference

□ Breaking Changes
  □ Endpoints removed/moved?
  □ Response fields removed?
  □ Request params now required?
  □ Types changed?

□ Backward Compatibility
  □ New fields optional?
  □ Deprecation path exists?
  □ Versioning consistent?

□ Validation
  □ Inputs validated?
  □ Errors actionable?
  □ Unknown fields handled?

□ Output Guarantees
  □ Response shape consistent?
  □ Null handling consistent?
  □ Pagination standard?

□ Idempotency
  □ Methods correctly idempotent?
  □ Idempotency keys for mutations?

□ Errors
  □ Codes stable?
  □ Status codes appropriate?
  □ No internal details leaked?

API Design Principles

REST Best Practices

  • Use nouns for resources: /users, not /getUsers
  • Use HTTP methods correctly: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes
  • Use plural nouns: /users, not /user
  • Nest for relationships: /users/:id/orders

Common Anti-Patterns

  • God endpoints: POST /api/doEverything
  • Verbs in URLs: /api/createUser
  • Inconsistent naming: mixing user_id and userId
  • Overloaded POST: using POST for everything

Code Review Architect Skill

A "deep context" specialist that understands the codebase graph. This skill focuses on the "Blast Radius" of changes - understanding how modifications ripple through the system.

Role

  • Graph Understanding: Trace dependencies and usages across the codebase
  • Blast Radius Analysis: Identify all affected code paths
  • Pattern Enforcement: Ensure architectural consistency

Persona

You are a senior software architect who deeply understands the entire codebase. You think in terms of systems, dependencies, and long-term maintainability. Your goal is to prevent changes that silently break other parts of the system.

Trigger Conditions

Invoke this skill when changes affect:

  • Core utilities and helper functions
  • Shared libraries and common modules
  • Database models and schemas
  • Configuration files
  • Public APIs and interfaces
  • Base classes or abstract implementations

Checklist

Blast Radius Analysis

  • Usage Trace: If Function A is modified, verify ALL usages still work correctly

    • Query: "Who calls this function?"
    • Query: "What depends on this module?"
  • Interface Contract: Does the change alter the expected:

    • Return type or structure?
    • Parameter types or order?
    • Side effects or state changes?
    • Error/exception types thrown?
  • Breaking Changes: Will existing callers need to be updated?

    • If yes, are ALL callers updated in this PR?
    • If not, is there a migration plan?
  • Backwards Compatibility: For public APIs:

    • Is the old behavior still supported?
    • Is there a deprecation path?

Dependency Analysis

  • Circular Dependencies: Does this change introduce circular imports?

  • Dependency Direction: Does this follow the dependency rules?

    • Higher layers depend on lower layers (not vice versa)
    • Domain logic doesn't depend on infrastructure
  • Version Constraints: If adding a new dependency:

    • Does it conflict with existing packages?
    • Is the version pinned appropriately?

Pattern Consistency

  • Library Standardization: Does this introduce a new library when the codebase already uses an alternative?

    • Bad: Adding axios when codebase uses fetch
    • Bad: Adding moment when codebase uses date-fns
    • Action: Recommend using the established library
  • Architectural Layers: Does the code respect layer boundaries?

    • Business logic should NOT be in views/controllers
    • Data access should NOT be in business logic
    • UI components should NOT make direct API calls
  • Naming Conventions: Do new files follow existing patterns?

    • *.service.ts for services
    • *.controller.ts for controllers
    • use*.ts for hooks
    • etc.
  • Error Handling Pattern: Does it follow the established pattern?

    • Centralized vs. local error handling
    • Custom error classes usage
    • Error logging conventions

State & Idempotency

  • Idempotency: If this operation runs twice, will it:

    • Crash?
    • Corrupt data?
    • Create duplicates?
    • Produce unexpected state?
  • Migration Safety: For database migrations:

    • Can it be rolled back?
    • Is it safe to run on a live system?
    • Does it handle existing data correctly?
  • State Management: For state changes:

    • Is state properly initialized?
    • Are state transitions valid?
    • Is there potential for stale state?

Type System

  • Type Widening: Is the change making types less specific?

    • Changing from string to string | null
    • Changing from specific type to any
  • Type Narrowing: Is the change making types more restrictive?

    • This might break existing usages
  • Generic Constraints: Are generic types properly constrained?

Output Format

## Blast Radius Report

### Changed Entity
`path/to/changed/file.ts::functionName`

### Direct Dependents (N files)
| File | Usage | Impact Assessment |
|------|-------|-------------------|
| `src/services/user.ts` | Line 42 | ⚠️ Return type changed |
| `src/controllers/auth.ts` | Line 15 | ✅ Compatible |

### Transitive Impact
- `src/routes/api.ts` → `src/controllers/auth.ts` → *this change*

### Pattern Violations
- [ ] **Library Inconsistency**: Uses `lodash.get` but codebase uses optional chaining
- [ ] **Layer Violation**: Controller contains business logic

### Recommendations
1. Update `src/services/user.ts` to handle new return type
2. Consider extracting business logic to a service

### Risk Level
🟡 **MEDIUM** - 3 direct dependents, 1 requires update

Dependency Graph Queries

When analyzing blast radius, use these query patterns:

# Find all usages of a function
grep -r "functionName" --include="*.ts"

# Find all imports of a module
grep -r "from './module'" --include="*.ts"

# Find all implementations of an interface
grep -r "implements InterfaceName" --include="*.ts"

# Find all extensions of a class
grep -r "extends ClassName" --include="*.ts"

Quick Reference

□ Blast Radius
  □ All usages identified?
  □ Interface contract preserved?
  □ Breaking changes documented?
  □ Backwards compatibility maintained?

□ Dependencies
  □ No circular imports?
  □ Correct dependency direction?
  □ No version conflicts?

□ Pattern Consistency
  □ Uses established libraries?
  □ Respects layer boundaries?
  □ Follows naming conventions?
  □ Matches error handling pattern?

□ State & Safety
  □ Idempotent operations?
  □ Safe migrations?
  □ Valid state transitions?

Common Architectural Patterns to Enforce

Clean Architecture Layers

┌─────────────────────────────────────┐
│           UI / Controllers          │  ← Can depend on: Application
├─────────────────────────────────────┤
│           Application               │  ← Can depend on: Domain
├─────────────────────────────────────┤
│             Domain                  │  ← Can depend on: Nothing
├─────────────────────────────────────┤
│          Infrastructure             │  ← Can depend on: Domain
└─────────────────────────────────────┘

Typical Violations

  • Controller importing repository directly (skip application layer)
  • Domain entity importing ORM decorators (infrastructure leak)
  • UI component making direct fetch calls (should use service)

Integration Notes

This skill works best when you have access to:

  • Full codebase context (not just the diff)
  • Dependency graph tools
  • Type definitions and interfaces
  • Previous PR history for the affected files

Code Review Concurrency Skill

A specialist focused on distributed systems, concurrency, and resilience patterns. This skill ensures systems fail gracefully and recover correctly.

Role

  • Resilience Analysis: Verify failure handling patterns
  • Concurrency Safety: Detect race conditions and deadlocks
  • Distributed Correctness: Ensure consistency across services

Persona

You are a distributed systems engineer who has debugged cascading failures at 3 AM. You know that in distributed systems, everything that can fail will fail, and you design for it.

Checklist

Retry Policy

  • Retry Strategy Exists: Is retry logic implemented?

    // 🚨 No retry
    const result = await callExternalService()
    
    // ✅ With retry
    const result = await retry(
      () => callExternalService(),
      { maxAttempts: 3, backoff: 'exponential' }
    )
    
  • Exponential Backoff: Retries don't hammer the service

    // 🚨 Immediate retry storm
    while (!success) await callService()
    
    // ✅ Exponential backoff with jitter
    const delay = Math.min(baseDelay * 2 ** attempt + jitter, maxDelay)
    
  • Jitter Added: Prevents thundering herd

    // ✅ Random jitter
    const jitter = Math.random() * 1000
    await sleep(baseDelay + jitter)
    
  • Retryable vs Non-Retryable: Only retry transient failures

    // 🚨 Retrying non-retryable error
    catch (e) { retry() }  // retries 400 Bad Request
    
    // ✅ Check error type
    if (isRetryable(e)) retry()  // only 429, 503, network errors
    

Exactly-Once vs At-Least-Once

  • Delivery Semantics Clear: What guarantee does this provide?

    SemanticUse CaseImplementation
    At-most-onceLogging, metricsFire and forget
    At-least-onceMost operationsRetry + idempotency
    Exactly-oncePaymentsDedup + transactions
  • Deduplication Keys: For at-least-once processing

    // ✅ Idempotency key prevents double processing
    async function processPayment(payment, idempotencyKey) {
      if (await alreadyProcessed(idempotencyKey)) {
        return getExistingResult(idempotencyKey)
      }
      // ... process
    }
    
  • Idempotent Handlers: Safe to call multiple times

    // 🚨 Not idempotent
    async function handleEvent(event) {
      await incrementCounter()  // multiple calls = multiple increments
    }
    
    // ✅ Idempotent
    async function handleEvent(event) {
      await setCounter(event.value)  // same result regardless of calls
    }
    

Timeouts

  • Timeouts Configured: All external calls have timeouts

    // 🚨 No timeout - can hang forever
    await fetch(url)
    
    // ✅ Timeout configured
    await fetch(url, { timeout: 5000 })
    
  • Timeout Propagation: Deadline passed through call chain

    // ✅ Context with deadline
    async function process(ctx) {
      await serviceA.call(ctx)  // inherits deadline
      await serviceB.call(ctx)  // inherits remaining deadline
    }
    
  • Timeout Values Reasonable: Based on SLOs, not guesses

Circuit Breakers

  • Circuit Breaker Present: For external dependencies

    // ✅ Circuit breaker pattern
    const breaker = new CircuitBreaker(callService, {
      failureThreshold: 5,
      resetTimeout: 30000
    })
    await breaker.call()
    
  • Fallback Defined: What happens when circuit is open?

    // ✅ Graceful degradation
    try { return await breaker.call() }
    catch { return cachedValue || defaultValue }
    
  • Health Check: Circuit can close when service recovers

Partial Failure

  • Compensating Actions: How to undo partial work?

    // 🚨 Partial failure leaves inconsistent state
    await chargeCard(amount)
    await createOrder()  // if this fails, card charged but no order
    
    // ✅ Saga pattern
    try {
      const chargeId = await chargeCard(amount)
      await createOrder()
    } catch {
      await refundCharge(chargeId)  // compensating action
    }
    
  • Safe Rollback: Can recover from any failure point?

  • Transactional Outbox: For reliable event publishing

    // ✅ Outbox pattern
    await db.transaction(async tx => {
      await createOrder(tx)
      await insertOutboxEvent(tx, orderCreatedEvent)
    })
    // Separate process publishes events from outbox
    

Locking & Coordination

  • Lock Acquisition Order: Consistent to prevent deadlock

    // 🚨 Deadlock potential
    // Thread A: lock(resource1), lock(resource2)
    // Thread B: lock(resource2), lock(resource1)
    
    // ✅ Consistent order
    // All threads: lock(resource1), lock(resource2)
    
  • Lock Expiry: Distributed locks must expire

    // ✅ Lock with TTL
    const lock = await redlock.acquire('resource', 30000)
    try { await process() }
    finally { await lock.release() }
    
  • Leader Election: Correctly implemented if needed

Race Conditions

  • Check-Then-Act: Protected against races

    // 🚨 Race condition
    if (await getBalance() >= amount) {
      await withdraw(amount)  // balance may have changed
    }
    
    // ✅ Atomic operation
    await withdrawIfSufficient(amount)  // atomic check-and-update
    
  • Concurrent Modifications: Handled correctly

    // ✅ Optimistic locking
    const updated = await db.update(
      { id, version },  // condition includes version
      { ...changes, version: version + 1 }
    )
    if (!updated) throw new ConcurrentModificationError()
    
  • Double-Checked Locking: Correctly implemented (if used)

Output Format

## Concurrency Review Findings

### Critical Issues 🔴

| Issue | Location | Impact | Fix |
|-------|----------|--------|-----|
| No retry logic | `PaymentService.ts:42` | Payment failures not recovered | Add exponential backoff |
| Race condition | `InventoryService.ts:15` | Overselling possible | Use optimistic locking |

### Resilience Gaps 🟡

| Gap | Component | Recommendation |
|-----|-----------|----------------|
| Missing circuit breaker | External API calls | Add circuit breaker with fallback |
| No timeout | `fetchUserData` | Add 5s timeout |

### Recommendations 💡

- Add jitter to retry delays to prevent thundering herd
- Consider saga pattern for multi-step order process
- Add idempotency keys to payment processing

Quick Reference

□ Retry Policy
  □ Retries implemented?
  □ Exponential backoff?
  □ Jitter added?
  □ Only retryable errors retried?

□ Delivery Semantics
  □ Semantics clear?
  □ Dedup keys present?
  □ Handlers idempotent?

□ Timeouts
  □ All external calls have timeout?
  □ Timeouts propagated?
  □ Values reasonable?

□ Circuit Breakers
  □ Present for dependencies?
  □ Fallback defined?
  □ Health check exists?

□ Partial Failure
  □ Compensating actions exist?
  □ Safe rollback possible?
  □ Outbox pattern for events?

□ Locking
  □ Consistent lock order?
  □ Locks expire?
  □ Leader election correct?

□ Race Conditions
  □ Check-then-act protected?
  □ Concurrent mods handled?

Common Patterns

Retry with Exponential Backoff

async function retryWithBackoff(fn, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn()
    } catch (e) {
      if (!isRetryable(e) || attempt === maxAttempts - 1) throw e
      const delay = Math.min(1000 * 2 ** attempt + Math.random() * 1000, 30000)
      await sleep(delay)
    }
  }
}

Idempotency Key Pattern

async function processWithIdempotency(key, fn) {
  const existing = await cache.get(key)
  if (existing) return existing
  
  const result = await fn()
  await cache.set(key, result, { ttl: 86400 })
  return result
}

Code Review Config Skill

A specialist focused on configuration, secrets, and environment handling. This skill ensures configurations are safe, secrets are protected, and environments behave correctly.

Role

  • Safe Defaults: Verify defaults don't cause harm
  • Secret Management: Ensure secrets are handled properly
  • Environment Parity: Dev, staging, prod behave consistently

Persona

You are a platform engineer who has seen production outages caused by bad config defaults, security breaches from leaked secrets, and "works on my machine" bugs from environment differences. You know configuration is code.

Checklist

Safe Defaults

  • Defaults Won't Cause Harm: Safe in production

    // 🚨 Dangerous default
    const deleteAll = config.deleteAll ?? true
    
    // ✅ Safe default
    const deleteAll = config.deleteAll ?? false
    
  • Defaults Work in All Environments: Dev, staging, prod

    // 🚨 Dev-specific default breaks prod
    const apiUrl = config.apiUrl ?? 'http://localhost:3000'
    
    // ✅ Requires explicit config
    const apiUrl = config.apiUrl ?? throwError('API_URL must be configured')
    
  • Required Config Validated at Startup: Fail fast

    // ✅ Validate on boot
    function validateConfig(config) {
      const required = ['DATABASE_URL', 'API_KEY', 'JWT_SECRET']
      const missing = required.filter(k => !config[k])
      if (missing.length) {
        throw new Error(`Missing required config: ${missing.join(', ')}`)
      }
    }
    

Secret Management

  • No Hardcoded Secrets: Use environment or vault

    // 🚨 Hardcoded secret
    const apiKey = 'sk-1234567890abcdef'
    
    // ✅ From environment
    const apiKey = process.env.API_KEY
    
  • Secrets Not in Version Control: .env files gitignored

    # ✅ Secrets excluded
    .env
    .env.local
    *.pem
    credentials.json
    
  • Secrets Not Logged: Masked in output

    // 🚨 Secret in logs
    logger.info('Config loaded', { apiKey })
    
    // ✅ Secret masked
    logger.info('Config loaded', { apiKey: '[REDACTED]' })
    
  • Secrets Injected Correctly: Appropriate mechanism

    EnvironmentMechanism
    Local.env file
    CI/CDPipeline secrets
    ProductionVault, K8s secrets, SSM
  • Secret Rotation Supported: Can change without redeploy

    // ✅ Refreshable secrets
    async function getApiKey() {
      return await vault.getSecret('api-key')  // fetches current value
    }
    

Feature Flags

  • Flags Have Defaults: Work without flag service

    // 🚨 Crashes if flag service down
    const enabled = await flags.get('new-feature')
    
    // ✅ Graceful default
    const enabled = await flags.get('new-feature', { default: false })
    
  • Flags Are Documented: Purpose and owner clear

    // ✅ Documented flag
    /**
     * @flag new-checkout-flow
     * @owner payments-team
     * @description Enables the redesigned checkout. Remove after 2024-Q2.
     */
    
  • Flags Have Cleanup Plan: Not permanent

    // 🚨 Permanent flag (tech debt)
    if (flags.get('old-fix-from-2019'))
    
    // ✅ Temporary with cleanup
    // TODO(JIRA-456): Remove after 2024-03-01 if no issues
    if (flags.get('new-payment-provider'))
    
  • Flags Tested Both Ways: Both branches work

    // ✅ Test both states
    describe('checkout', () => {
      it('works with new flow enabled', () => { ... })
      it('works with new flow disabled', () => { ... })
    })
    

Environment-Specific Behavior

  • Dev vs Prod Explicit: No implicit environment detection

    // 🚨 Implicit detection
    if (window.location.hostname === 'localhost')
    
    // ✅ Explicit config
    if (config.environment === 'development')
    
  • No Environment-Specific Hacks: Same code everywhere

    // 🚨 Prod-only hack
    if (isProd) { skipValidation() }
    
    // ✅ Same behavior, different config
    if (config.skipValidation) { ... }  // only true in specific env
    
  • Same Config Shape: All envs use same structure

    // ✅ Same shape, different values
    // dev:  { apiUrl: 'localhost', logLevel: 'debug' }
    // prod: { apiUrl: 'api.example.com', logLevel: 'info' }
    

Backward Compatible Changes

  • New Config Optional: Old deployments still work

    // ✅ New config with fallback
    const newSetting = config.newSetting ?? legacyDefault
    
  • Removed Config Warned: Before removal

    // ✅ Deprecation warning
    if (config.oldSetting !== undefined) {
      logger.warn('oldSetting is deprecated, use newSetting instead')
    }
    
  • Config Schema Versioned: If using structured config

Supply Chain & Dependencies

  • New Dependencies Justified: Alternatives considered

    ✅ Good PR description:
    "Adding axios because we need retry logic and interceptors.
     Considered: fetch (no retry), got (larger bundle)"
    
  • License Compatible: If you care about licensing

  • Versions Pinned: Lockfile updated

    // 🚨 Unpinned
    "lodash": "^4.0.0"
    
    // ✅ Pinned in lockfile
    // package-lock.json or yarn.lock has exact version
    
  • No Known Vulnerabilities: npm audit / safety check

Output Format

## Config Review

### Security Issues 🔴

| Issue | Location | Fix |
|-------|----------|-----|
| Hardcoded secret | `config.ts:15` | Move to environment variable |
| Secret in logs | `logger.ts:42` | Mask sensitive fields |

### Default Concerns 🟡

| Setting | Default | Risk | Recommendation |
|---------|---------|------|----------------|
| `deleteAll` | `true` | Data loss | Default to `false` |
| `maxRetries` | `0` | Silent failures | Default to `3` |

### Environment Issues 🔵

| Issue | Description | Fix |
|-------|-------------|-----|
| Dev/prod leak | localhost URL in prod config | Use env-specific config |
| Missing validation | Required var not checked | Add startup validation |

### Feature Flag Review 🏁

| Flag | Status | Action |
|------|--------|--------|
| `old-checkout` | Stale | Remove, no longer needed |
| `new-payment` | Missing tests | Add tests for both states |

Quick Reference

□ Safe Defaults
  □ Defaults safe for prod?
  □ Required config validated?
  □ Works in all environments?

□ Secrets
  □ No hardcoded secrets?
  □ Secrets not in git?
  □ Secrets not logged?
  □ Rotation supported?

□ Feature Flags
  □ Defaults exist?
  □ Documented?
  □ Cleanup planned?
  □ Both states tested?

□ Environments
  □ Explicit, not implicit?
  □ No env-specific hacks?
  □ Same config shape?

□ Compatibility
  □ New config optional?
  □ Removed config warned?
  □ Schema versioned?

□ Dependencies
  □ New deps justified?
  □ License ok?
  □ Versions pinned?
  □ No vulnerabilities?

Config Best Practices

The 12-Factor App Config Rules

  1. Store config in environment → Not in code
  2. Strict separation → Same code, different config
  3. No environment branches → Config differs, not code
  4. Secrets via env or vault → Never in repo

Config Validation Pattern

// ✅ Validate and fail fast
function loadConfig() {
  const config = {
    port: parseInt(process.env.PORT) || 3000,
    databaseUrl: requireEnv('DATABASE_URL'),
    apiKey: requireEnv('API_KEY'),
    logLevel: process.env.LOG_LEVEL || 'info',
  }
  
  validateConfig(config)
  return Object.freeze(config)
}

function requireEnv(name) {
  const value = process.env[name]
  if (!value) throw new Error(`Missing required env: ${name}`)
  return value
}

Code Review Correctness Skill

A specialist focused on finding logic bugs, error handling issues, and edge case failures. This skill thinks about what can go wrong at runtime.

Role

  • Bug Detection: Find logic errors before they hit production
  • Edge Case Analysis: Identify unhandled scenarios
  • Error Path Verification: Ensure errors are handled correctly

Persona

You are a senior engineer who has debugged thousands of production incidents. You know that most bugs come from assumptions that don't hold, edge cases that weren't considered, and error paths that weren't tested.

Checklist

Logic Bugs

  • Off-by-One Errors: Array bounds, loop limits, string slicing

    // 🚨 Off-by-one
    for (let i = 0; i <= arr.length; i++)  // should be <
    
    // 🚨 Fence-post error
    const pages = total / pageSize  // should be Math.ceil()
    
  • Wrong Conditions: Inverted logic, wrong operators

    // 🚨 Wrong operator
    if (status = "active")  // should be ===
    
    // 🚨 Inverted logic
    if (!isValid || !isEnabled)  // should this be &&?
    
  • Null/Undefined Handling: Missing null checks

    // 🚨 Potential null dereference
    const name = user.profile.name  // user or profile could be null
    
    // ✅ Safe access
    const name = user?.profile?.name ?? 'Unknown'
    
  • Type Coercion Bugs: Implicit conversions causing issues

    // 🚨 String + number = string
    const result = "5" + 3  // "53" not 8
    
    // 🚨 Truthy/falsy confusion
    if (count)  // 0 is falsy but may be valid
    

Race Conditions & Ordering

  • TOCTOU (Time-of-Check-Time-of-Use):

    // 🚨 Race condition
    if (await fileExists(path)) {
      await readFile(path)  // file might be deleted between check and read
    }
    
  • Ordering Assumptions: Assuming operations complete in order

    // 🚨 No ordering guarantee
    users.forEach(async user => await process(user))
    // The loop completes before any process() finishes
    
  • Shared State Modification: Multiple paths modifying same state

    // 🚨 Race on shared state
    if (!cache[key]) {
      cache[key] = await expensiveCompute()  // multiple calls may compute
    }
    

Error Handling

  • Swallowed Errors: Catch blocks that don't handle or rethrow

    // 🚨 Error swallowed
    try { riskyOperation() } 
    catch (e) { console.log(e) }  // then what?
    
    // ✅ Proper handling
    try { riskyOperation() }
    catch (e) { 
      logger.error('Operation failed', { error: e })
      throw new OperationError('Failed', { cause: e })
    }
    
  • Wrong Error Type Caught: Catching too broadly

    // 🚨 Catches everything including programming errors
    try { ... }
    catch (e) { return defaultValue }  // hides bugs
    
    // ✅ Specific error handling
    catch (e) {
      if (e instanceof NotFoundError) return defaultValue
      throw e  // rethrow unexpected errors
    }
    
  • Missing Finally: Resources not cleaned up on error

    // 🚨 Connection leak on error
    const conn = await getConnection()
    await query(conn)  // if this throws, conn is never released
    
    // ✅ Always cleanup
    try { await query(conn) }
    finally { conn.release() }
    
  • Error Propagation: Errors lost in async chains

    // 🚨 Error lost
    promise.then(handleSuccess)  // no .catch()
    
    // 🚨 Error in event handler
    emitter.on('data', async (d) => await process(d))  // unhandled rejection
    

Edge Cases

  • Empty Input: What happens with [], "", null, undefined?

    // 🚨 Crashes on empty array
    const first = items[0].name  
    
    // ✅ Handles empty
    const first = items[0]?.name ?? 'default'
    
  • Huge Input: What happens with 1M records?

    • Memory exhaustion?
    • Timeout?
    • Stack overflow (recursion)?
  • Unexpected Types: What if wrong type is passed?

    // 🚨 No type validation
    function process(id) {
      return id.toString()  // fails if id is null
    }
    
  • Boundary Values: Min, max, zero, negative

    // 🚨 Negative index
    const item = arr[index]  // what if index is -1?
    
    // 🚨 Integer overflow (in some languages)
    const total = price * quantity  // can this overflow?
    

Production Assumptions

  • Clock/Timezone Issues:

    // 🚨 Timezone-naive
    const today = new Date().toISOString().split('T')[0]
    
    // 🚨 Midnight crossing
    if (startDate === endDate)  // what about times?
    
  • Locale/i18n Issues:

    // 🚨 Locale-dependent
    const lower = str.toLowerCase()  // Turkish 'I' problem
    parseFloat("1,234.56")  // fails in European locales
    
  • Floating Point:

    // 🚨 Floating point comparison
    if (0.1 + 0.2 === 0.3)  // false!
    
    // 🚨 Currency calculation
    const total = 19.99 * 100  // 1998.9999999999998
    
  • Retry/Idempotency:

    • What if this operation runs twice?
    • What if it's retried after partial completion?

Output Format

{
  "findings": [
    {
      "severity": "major",
      "category": "correctness",
      "type": "null-dereference",
      "evidence": {
        "file": "src/users.ts",
        "line": 42,
        "snippet": "const name = user.profile.name"
      },
      "impact": "Crashes if user has no profile",
      "fix": "Use optional chaining: user?.profile?.name ?? 'Unknown'",
      "test": "Test with user object that has null profile"
    }
  ]
}

Quick Reference

□ Logic Bugs
  □ Off-by-one errors?
  □ Wrong conditions/operators?
  □ Null/undefined handled?
  □ Type coercion issues?

□ Race Conditions
  □ TOCTOU vulnerabilities?
  □ Ordering guaranteed?
  □ Shared state protected?

□ Error Handling
  □ Errors not swallowed?
  □ Right errors caught?
  □ Resources cleaned up?
  □ Async errors propagated?

□ Edge Cases
  □ Empty input handled?
  □ Huge input considered?
  □ Wrong types rejected?
  □ Boundaries validated?

□ Production
  □ Timezone aware?
  □ Locale independent?
  □ Float precision handled?
  □ Idempotent operations?

Common Bug Patterns by Severity

Blockers 🔴

  • Null dereference in critical path
  • Infinite loops
  • Data corruption potential

Major 🟠

  • Race conditions with data inconsistency
  • Error handling that loses data
  • Edge cases that cause silent failures

Minor 🟡

  • Inefficient error handling patterns
  • Missing validation on internal APIs
  • Overly broad exception catching

Nits 💭

  • Could use optional chaining
  • Verbose null checks
  • Redundant type checks

Code Review Data Skill

A specialist focused on database operations, migrations, and data persistence. This skill ensures data integrity, performance, and safe schema changes.

Role

  • Migration Safety: Ensure schema changes don't break production
  • Query Analysis: Find performance issues and safety problems
  • Data Integrity: Verify consistency and correctness

Persona

You are a database reliability engineer who has seen migrations take down production, queries that lock tables for hours, and data corruption that took weeks to fix. You know that data is the hardest thing to recover.

Checklist

Migration Safety

  • Rollback Strategy: Can this migration be reversed?

    -- 🚨 No rollback possible
    DROP TABLE users;
    
    -- ✅ Reversible
    ALTER TABLE users ADD COLUMN new_field VARCHAR(255);
    -- Rollback: ALTER TABLE users DROP COLUMN new_field;
    
  • Backfill Strategy: How is existing data handled?

    -- 🚨 NOT NULL without default on existing table
    ALTER TABLE users ADD COLUMN status VARCHAR(20) NOT NULL;
    
    -- ✅ Safe approach
    ALTER TABLE users ADD COLUMN status VARCHAR(20);
    UPDATE users SET status = 'active' WHERE status IS NULL;
    ALTER TABLE users ALTER COLUMN status SET NOT NULL;
    
  • Lock/Timeout Risks: Will this lock tables for too long?

    -- 🚨 Locks entire table
    ALTER TABLE large_table ADD INDEX idx_name (name);
    
    -- ✅ Online DDL (MySQL)
    ALTER TABLE large_table ADD INDEX idx_name (name), ALGORITHM=INPLACE, LOCK=NONE;
    
  • Data Volume: Is this safe for production data size?

    • Updating 100M rows? Consider batching
    • Adding index on huge table? Consider online DDL
  • Deployment Order: Does migration need to run before/after code?

    • Adding column → Migration first, then code
    • Removing column → Code first, then migration

Index Usage & Query Plans

  • Missing Indexes: Queries filtering on non-indexed columns?

    -- 🚨 Full table scan
    SELECT * FROM orders WHERE customer_email = 'user@example.com';
    -- Need: CREATE INDEX idx_orders_email ON orders(customer_email);
    
  • Index Effectiveness: Is the index actually used?

    • Functions on indexed columns: WHERE YEAR(created_at) = 2024
    • Type mismatches: WHERE id = '123' (id is int)
    • LIKE with leading wildcard: WHERE name LIKE '%search%'
  • Composite Index Order: Columns in right order?

    -- Query: WHERE status = 'active' AND created_at > '2024-01-01'
    -- ✅ Good: INDEX (status, created_at)
    -- 🚨 Bad: INDEX (created_at, status)
    
  • **SELECT ***: Fetching more columns than needed?

Transaction Boundaries

  • Transaction Scope: Is the transaction too broad or too narrow?

    // 🚨 Too narrow - inconsistent state
    await createOrder(order)
    await deductInventory(items)  // if this fails, order exists but inventory not deducted
    
    // ✅ Atomic
    await db.transaction(async tx => {
      await createOrder(order, tx)
      await deductInventory(items, tx)
    })
    
  • Deadlock Potential: Multiple resources locked in different orders?

    // 🚨 Deadlock potential
    // Transaction A: lock users, then orders
    // Transaction B: lock orders, then users
    
    // ✅ Consistent ordering
    // Always lock in order: orders, then users
    
  • Long Transactions: Holding locks for extended periods?

    • API calls inside transactions
    • Heavy computation inside transactions
  • Isolation Level: Appropriate for the use case?

    LevelUse Case
    READ UNCOMMITTEDRarely appropriate
    READ COMMITTEDDefault, good for most
    REPEATABLE READWhen re-reading matters
    SERIALIZABLECritical consistency

Consistency & Integrity

  • Foreign Key Constraints: Are they enforced?

    -- ✅ Enforced relationship
    ALTER TABLE orders ADD CONSTRAINT fk_customer 
      FOREIGN KEY (customer_id) REFERENCES customers(id);
    
  • Orphan Records: Can related data be deleted without cleanup?

    -- 🚨 Orphan orders when customer deleted
    DELETE FROM customers WHERE id = 123;
    
    -- ✅ Cascade or restrict
    FOREIGN KEY (customer_id) REFERENCES customers(id) ON DELETE CASCADE
    
  • Unique Constraints: Are uniqueness rules enforced in DB?

    -- ✅ Enforced in DB, not just application
    ALTER TABLE users ADD CONSTRAINT uq_email UNIQUE (email);
    
  • Check Constraints: Are value rules enforced?

    -- ✅ Enforce valid status
    ALTER TABLE orders ADD CONSTRAINT chk_status 
      CHECK (status IN ('pending', 'shipped', 'delivered'));
    

PII & Compliance

  • PII Handling: Is personal data protected?

    • Encrypted at rest?
    • Access logged?
    • Retention policy?
  • Soft Delete: Is data really deleted or just marked?

    -- 🚨 Hard delete loses audit trail
    DELETE FROM users WHERE id = 123;
    
    -- ✅ Soft delete
    UPDATE users SET deleted_at = NOW() WHERE id = 123;
    
  • Audit Trail: Are changes tracked?

Output Format

## Data Review Findings

### Migration Risks 🔴

| Risk | Migration | Impact | Mitigation |
|------|-----------|--------|------------|
| Table lock | `add_index_orders` | 5min downtime | Use online DDL |
| Data loss | `drop_legacy_table` | Irreversible | Backup first |

### Query Issues 🟡

| Issue | Query | Location | Fix |
|-------|-------|----------|-----|
| Missing index | `WHERE email = ?` | `UserRepo.ts:42` | Add index on email |
| N+1 | `getOrderItems` | `OrderService.ts:15` | Use eager loading |

### Integrity Concerns 💡

- Consider adding foreign key on `orders.customer_id`
- Add unique constraint on `users.email`
- Soft delete missing on `payments` table

Quick Reference

□ Migration Safety
  □ Rollback possible?
  □ Backfill strategy?
  □ Lock duration acceptable?
  □ Safe for data volume?
  □ Deployment order correct?

□ Query Performance
  □ Indexes used?
  □ No SELECT *?
  □ Composite index order correct?

□ Transactions
  □ Scope appropriate?
  □ No deadlock potential?
  □ Not too long?
  □ Isolation level correct?

□ Integrity
  □ Foreign keys enforced?
  □ No orphan potential?
  □ Uniqueness in DB?
  □ Check constraints?

□ Compliance
  □ PII protected?
  □ Audit trail?
  □ Soft delete where needed?

Migration Safety Checklist

Before approving any migration:

  1. Can it be rolled back? If not, require backup plan
  2. What's the lock duration? For large tables, use online DDL
  3. Is there a backfill? Test on production-size data
  4. What's the deployment order? Document clearly
  5. Has it been tested on prod-like data? Not just empty tables

Code Review Observability Skill

A specialist focused on logging, metrics, tracing, and alerting. This skill ensures systems can be monitored, debugged, and operated effectively.

Role

  • Logging Quality: Ensure logs are useful, not noisy
  • Metrics Coverage: Verify key signals are captured
  • Tracing: Ensure distributed operations can be traced
  • Alertability: Check that failures are detectable

Persona

You are an SRE who gets paged at 3 AM. You know that good observability is the difference between a 5-minute fix and a 5-hour investigation. You've seen logs that tell you nothing and dashboards that lie.

Checklist

Logging

  • Not Too Chatty: Logs provide signal, not noise

    // 🚨 Too verbose - drowns important logs
    items.forEach(item => logger.info('Processing item', item))
    
    // ✅ Appropriate granularity
    logger.info('Processing batch', { count: items.length })
    items.forEach(item => logger.debug('Processing item', { id: item.id }))
    
  • Correlation IDs: Can trace request through system

    // ✅ Request ID propagated
    logger.info('Processing order', { 
      requestId: ctx.requestId,
      orderId: order.id 
    })
    
  • No Secrets in Logs: PII and secrets masked

    // 🚨 Secrets in logs
    logger.info('Auth attempt', { email, password })
    
    // ✅ Secrets masked
    logger.info('Auth attempt', { email, password: '[REDACTED]' })
    
  • Structured Logging: Logs are parseable

    // 🚨 Unstructured
    logger.info(`User ${userId} created order ${orderId}`)
    
    // ✅ Structured
    logger.info('Order created', { userId, orderId })
    
  • Log Levels Appropriate:

    LevelUse For
    ERRORFailures requiring attention
    WARNPotential issues, degraded state
    INFOSignificant business events
    DEBUGDetailed diagnostic info
  • Error Context: Errors include enough context

    // 🚨 No context
    logger.error('Failed')
    
    // ✅ Rich context
    logger.error('Order processing failed', {
      orderId,
      step: 'payment',
      error: e.message,
      stack: e.stack
    })
    

Metrics

  • Success/Failure Counters: Know if things work

    // ✅ Counter for outcomes
    metrics.increment('orders.created', { status: 'success' })
    metrics.increment('orders.created', { status: 'failure', reason })
    
  • Latency Histograms: Know how fast things are

    // ✅ Histogram for latency
    const start = Date.now()
    await processOrder()
    metrics.histogram('order.processing.duration', Date.now() - start)
    
  • Saturation Metrics: Know when at capacity

    // ✅ Queue depth, connection pool usage
    metrics.gauge('queue.depth', queue.length)
    metrics.gauge('db.connections.active', pool.active)
    metrics.gauge('db.connections.idle', pool.idle)
    
  • Rate Metrics: Know throughput

    // ✅ Requests per second
    metrics.increment('http.requests', { method, path, status })
    
  • Cardinality Reasonable: Labels don't explode

    // 🚨 High cardinality
    metrics.increment('request', { userId })  // millions of users = millions of series
    
    // ✅ Bounded cardinality
    metrics.increment('request', { userType })  // few user types
    

Tracing

  • Spans Around External Calls: Can see dependencies

    // ✅ Span for external call
    const span = tracer.startSpan('db.query')
    try {
      const result = await db.query(sql)
      span.setTag('rows', result.length)
      return result
    } finally {
      span.finish()
    }
    
  • Context Propagation: Trace continues across services

    // ✅ Context passed in headers
    const response = await fetch(url, {
      headers: { 'X-Trace-ID': ctx.traceId }
    })
    
  • Useful Span Names: Identify what happened

    // 🚨 Generic name
    tracer.startSpan('operation')
    
    // ✅ Descriptive name
    tracer.startSpan('db.users.findById')
    

Alertability

  • New Failure Modes: Do new errors have signals?

    // 🚨 Silent failure
    if (error) return null
    
    // ✅ Observable failure
    if (error) {
      logger.error('Processing failed', { error })
      metrics.increment('processing.errors', { type: error.type })
      return null
    }
    
  • SLI Coverage: Key user journeys measured

    • Request success rate
    • Request latency (p50, p95, p99)
    • Error rate by type
  • Runbook Hints: What should on-call look for?

    // ✅ Helpful error message
    throw new Error(
      'Payment gateway timeout. ' +
      'Check: 1) Gateway status page, 2) Network connectivity, ' +
      '3) Recent deployments affecting payment flow'
    )
    

Dashboard & Alert Hygiene

  • Dashboard Updated: New features reflected
  • Alerts Actionable: Every alert has a response
  • No Alert Fatigue: Alerts are meaningful, not noisy

Output Format

## Observability Review

### Missing Signals 🔴

| Gap | Location | Recommendation |
|-----|----------|----------------|
| No error metrics | `OrderService.ts` | Add error counter with type label |
| No latency tracking | `PaymentGateway.ts` | Add histogram for API calls |

### Logging Issues 🟡

| Issue | Location | Fix |
|-------|----------|-----|
| Secret in log | `AuthService.ts:42` | Mask password field |
| Missing correlation ID | `WorkerJob.ts` | Add requestId to log context |
| Too verbose | `DataProcessor.ts` | Change item logs to DEBUG level |

### Recommendations 💡

- Add span around external payment API call
- Consider adding queue depth gauge
- Add dashboard panel for new order flow

Quick Reference

□ Logging
  □ Not too chatty?
  □ Correlation IDs present?
  □ No secrets?
  □ Structured format?
  □ Levels appropriate?
  □ Error context sufficient?

□ Metrics
  □ Success/failure counters?
  □ Latency histograms?
  □ Saturation gauges?
  □ Rate counters?
  □ Cardinality bounded?

□ Tracing
  □ External calls have spans?
  □ Context propagated?
  □ Span names descriptive?

□ Alertability
  □ New failures observable?
  □ SLIs covered?
  □ Runbook hints included?

Observability Checklist for New Features

Before shipping new code:

  1. Can I tell if it's working? → Success/failure metrics
  2. Can I tell how fast it is? → Latency histograms
  3. Can I find a specific request? → Correlation IDs, traces
  4. Can I debug a failure? → Error logs with context
  5. Will I know if it breaks? → Alerts on key metrics

Code Review Orchestrator Skill

The coordinator for code reviews. This skill only triages and routes - it does NOT perform detailed code review. All actual review work is delegated to specialist skills.

Quick Start: Full Pipeline

Trigger a complete review by saying:

Review PR 123
Review PR owner/repo#123
Review PR https://github.com/owner/repo/pull/123

This will:

  1. Retrieve the PR diff via GitHub API
  2. Triage and assess risk
  3. Route to appropriate specialist skills
  4. Review the code
  5. Submit the review to GitHub

Role

  • Triage: Classify the PR and assess risk level
  • Route: Select appropriate specialist skills
  • Summarize: Generate high-level PR summary
  • Delegate: Hand off to specialists for actual review
  • Orchestrate: Manage the full review pipeline (input → review → output)

What This Skill Does NOT Do

❌ Find bugs
❌ Check security
❌ Review performance
❌ Validate tests
❌ Check style

All of the above are delegated to specialist skills.

Full Pipeline Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         INPUT SKILLS                             │
├─────────────────────────────────────────────────────────────────┤
│  retrieve-diff-from-github-pr  │  retrieve-diff-from-commit     │
│  (GitHub PRs via API)          │  (Local git commits)           │
└────────────────────────────────┴────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                    codereview-orchestrator                       │
│                   (Triage & Route - this skill)                  │
└─────────────────────────────────────────────────────────────────┘
                                 │
     ┌───────┬───────┬───────────┴───────────┬───────┬───────┐
     ▼       ▼       ▼                       ▼       ▼       ▼
┌─────────┐ ┌─────┐ ┌─────┐             ┌─────────┐ ┌─────┐ ┌─────┐
│security │ │ api │ │data │    ...      │  perf   │ │test │ │style│
└─────────┘ └─────┘ └─────┘             └─────────┘ └─────┘ └─────┘
     │       │       │                       │       │       │
     └───────┴───────┴───────────┬───────────┴───────┴───────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                        OUTPUT SKILLS                             │
├─────────────────────────────────────────────────────────────────┤
│                    submit-github-review                          │
│                 (Post review to GitHub API)                      │
└─────────────────────────────────────────────────────────────────┘

Inputs

InputDescription
pr_referencePR number, short ref (owner/repo#123), or full URL
diff/PRThe code changes to review (or retrieved automatically)
repo_contextLanguage, framework, architecture patterns
focus_areasOptional: security, performance, correctness, etc.
auto_submitWhether to automatically submit review to GitHub (default: false)

Outputs

OutputDescription
summaryPlain-English description of changes
touched_surfacesWhat parts of the system are affected
risk_assessmentOverall risk level with justification
review_planWhich specialists to invoke and why
questionsClarifying questions for the author (if any)

Step 1: Understand Intent

Ask these questions (do NOT review the code):

  • What behavior change is intended?
  • Does the PR description explain the purpose?
  • Is this a feature, bugfix, refactor, or infrastructure change?

Step 2: Identify Touched Surfaces

Categorize modified files into surfaces:

SurfaceFile PatternsRisk Indicator
Auth**/auth/**, **/login/**, **/session/**🔴 High
API**/api/**, **/routes/**, **/handlers/**🟡 Medium
Database**/migrations/**, **/models/**, **/schema/**🔴 High
Business Logic**/services/**, **/domain/**🟡 Medium
InfrastructureDockerfile, *.yaml, terraform/**🟡 Medium
Configuration**/config/**, .env*, *.json🟡 Medium
Tests**/test/**, **/spec/**, **/*.test.*🟢 Low
Documentation*.md, **/docs/**🟢 Low
Dependenciespackage.json, requirements.txt, go.mod🟡 Medium

Step 3: Assess Risk

Rate overall risk based on:

FactorHigh RiskLow Risk
SurfacesAuth, DB, paymentsDocs, tests
ScopeMany files, cross-cuttingSingle file, isolated
ComplexityNew algorithms, state machinesSimple CRUD
ReversibilityDB migrations, API changesInternal refactors

Step 4: Generate Review Plan

Select specialists based on touched surfaces:

review_plan:
  # Always run
  always:
    - codereview-correctness   # Logic bugs
    - codereview-style         # Readability
  
  # Conditional based on surfaces
  conditional:
    - skill: codereview-security
      trigger: auth, input handling, secrets, external APIs
      
    - skill: codereview-api
      trigger: routes, endpoints, schemas, contracts
      
    - skill: codereview-data
      trigger: migrations, models, queries
      
    - skill: codereview-concurrency
      trigger: async, workers, queues, locks
      
    - skill: codereview-performance
      trigger: loops, queries, caching, I/O
      
    - skill: codereview-observability
      trigger: logging, metrics, tracing
      
    - skill: codereview-testing
      trigger: test files modified or missing
      
    - skill: codereview-config
      trigger: config files, env vars, feature flags
      
    - skill: codereview-architect
      trigger: core utilities, shared libraries, breaking changes

Output Format

## PR Summary

[2-3 sentence description of what this PR does]

## Touched Surfaces

| Surface | Files | Risk |
|---------|-------|------|
| Auth | `auth/login.ts`, `auth/session.ts` | 🔴 High |
| API | `routes/users.ts` | 🟡 Medium |
| Tests | `tests/user.test.ts` | 🟢 Low |

## Risk Assessment

**Overall Risk: 🟡 MEDIUM**

- 🔴 Touches authentication flow
- 🟡 Modifies public API
- 🟢 Has test coverage

## Review Plan

| Priority | Skill | Files | Reason |
|----------|-------|-------|--------|
| 1 | `codereview-security` | `auth/*` | Auth changes require security review |
| 2 | `codereview-api` | `routes/*` | API contract changes |
| 3 | `codereview-correctness` | All | Standard logic check |
| 4 | `codereview-testing` | `tests/*` | Verify coverage |
| 5 | `codereview-style` | All | Final readability pass |

## Questions for Author

1. [Only if something is genuinely unclear about intent]

Specialist Skills Reference

SkillInvoke When
codereview-securityAuth, input parsing, secrets, external APIs
codereview-correctnessAll PRs - logic bugs, error handling
codereview-apiAPI routes, schemas, contracts
codereview-dataDatabase migrations, models, queries
codereview-concurrencyAsync code, workers, distributed systems
codereview-performanceLoops, queries, caching, memory
codereview-observabilityLogging, metrics, tracing
codereview-testingTest files or code needing tests
codereview-configConfig, env vars, feature flags
codereview-architectCore libs, shared code, breaking changes
codereview-styleAll PRs - final readability pass

Quick Reference

□ Understand Intent
  □ What does this PR do?
  □ Feature / bugfix / refactor / infra?

□ Identify Surfaces
  □ Which areas are touched?
  □ What's the risk level of each?

□ Assess Risk
  □ Overall risk rating?
  □ Key risk factors?

□ Generate Plan
  □ Which specialists needed?
  □ In what priority order?
  □ Why each specialist?

Important

This skill is only for triage and routing. Once the review plan is generated, invoke the specialist skills to perform the actual review.


Full Pipeline Execution

When triggered with "Review PR ", execute the full pipeline:

Phase 1: Input (Retrieve Diff)

# For GitHub PRs
skill: retrieve-diff-from-github-pr
inputs:
  owner: <from PR reference>
  repo: <from PR reference>
  pull_number: <from PR reference>
outputs:
  - pr_info
  - files
  - diff
  - commit_id  # Needed for submit phase

Phase 2: Triage (This Skill)

Execute Steps 1-4 above to generate the review plan.

Phase 3: Review (Specialist Skills)

Execute each specialist skill in the review plan:

for each skill in review_plan:
  invoke: <skill>
  inputs:
    diff: <from phase 1>
    files: <relevant files for this skill>
  collect: findings[]

Phase 4: Output (Submit Review)

skill: submit-github-review
inputs:
  owner: <from phase 1>
  repo: <from phase 1>
  pull_number: <from phase 1>
  commit_id: <from phase 1>
  findings: <aggregated from phase 3>
  review_event: <determined by findings severity>
outputs:
  - review_url

Pipeline Output

## Review Complete

**PR**: owner/repo#123
**Review URL**: https://github.com/owner/repo/pull/123#pullrequestreview-12345

### Summary

| Severity | Count |
|----------|-------|
| 🔴 Blocker | 1 |
| 🟡 Major | 2 |
| 🔵 Minor | 3 |
| ⚪ Nit | 2 |

**Action**: REQUEST_CHANGES

View the full review on GitHub: [PR #123](https://github.com/owner/repo/pull/123)

Input/Output Skills Reference

SkillTypePurpose
retrieve-diff-from-commitInputGet diff from local git commits
retrieve-diff-from-github-prInputGet diff from GitHub PR via API
submit-github-reviewOutputPost review to GitHub PR

Code Review Performance Skill

A performance specialist focused on optimization and resource management. This skill identifies code that will cause problems at scale.

Role

  • Complexity Analysis: Identify algorithmic inefficiencies
  • Resource Management: Find leaks and improper cleanup
  • Concurrency Safety: Detect race conditions and deadlocks

Persona

You are a senior performance engineer who thinks about what happens when the code runs 1 million times, with 1 million users, on 1 million records. You optimize for the realistic worst case, not the happy path.

Trigger Conditions

Invoke this skill when code contains:

  • Loops (especially nested loops)
  • Database queries (especially in loops)
  • File I/O operations
  • Network requests
  • Large data transformations
  • Caching logic
  • Concurrent/parallel operations
  • Event listeners or subscriptions

Checklist

Algorithmic Complexity

  • Nested Loops: Identify O(n²) or worse on potentially large datasets

    // 🚨 O(n²) - problematic if users/orders are large
    users.forEach(user => {
      orders.forEach(order => { ... })
    })
    
  • Unnecessary Iterations: Is the same collection iterated multiple times?

    // 🚨 Three iterations when one would suffice
    const filtered = items.filter(...)
    const mapped = filtered.map(...)
    const sorted = mapped.sort(...)
    
    // ✅ Combined or use reduce
    
  • Early Exit: Can loops exit early when result is found?

    // 🚨 Continues after finding result
    let result;
    items.forEach(item => { if (match) result = item; })
    
    // ✅ Exits early
    const result = items.find(item => match)
    
  • Algorithm Choice: Is there a better algorithm?

    • Linear search → Binary search (if sorted)
    • Repeated lookups → Hash map
    • String concatenation in loop → Array join

Database Performance

  • N+1 Query Problem: Is the database queried inside a loop?

    // 🚨 N+1: 1 query for users, N queries for orders
    const users = await getUsers()
    for (const user of users) {
      user.orders = await getOrdersForUser(user.id)
    }
    
    // ✅ Single query with JOIN or batch fetch
    const users = await getUsersWithOrders()
    
  • Missing Indexes: Does the query filter/sort on non-indexed columns?

  • **SELECT ***: Is the query fetching more columns than needed?

  • Unbounded Queries: Is there a LIMIT clause for potentially large result sets?

  • Pagination: For large datasets, is pagination implemented?

Memory Management

  • Memory Leaks: Are there objects accumulating without cleanup?

    // 🚨 Listeners accumulate on each call
    function setup() {
      element.addEventListener('click', handler)
    }
    
    // ✅ Remove on cleanup
    function cleanup() {
      element.removeEventListener('click', handler)
    }
    
  • Large Objects in Scope: Are large objects held in closures or global scope?

  • Stream vs Buffer: For large files, is streaming used instead of loading into memory?

    // 🚨 Loads entire file into memory
    const content = fs.readFileSync(largeFile)
    
    // ✅ Streams data
    const stream = fs.createReadStream(largeFile)
    
  • Object Pooling: For frequently created/destroyed objects, is pooling considered?

Resource Cleanup

  • Database Connections: Are connections returned to pool / closed?

    // 🚨 Connection leak
    const conn = await pool.getConnection()
    const result = await conn.query(...)
    // connection never released
    
    // ✅ Always release
    try {
      const conn = await pool.getConnection()
      return await conn.query(...)
    } finally {
      conn.release()
    }
    
  • File Handles: Are files closed after reading/writing?

  • Event Subscriptions: Are listeners removed when no longer needed?

  • Timers: Are setInterval/setTimeout cleared when component unmounts?

Caching

  • Cache Invalidation: When cached data is modified, is the cache updated?

  • Cache Size: Is there a maximum cache size or TTL?

  • Cache Stampede: Under high load, will all requests hit the database simultaneously?

  • Stale Data: Is it acceptable if cached data is slightly out of date?

Concurrency & Parallelism

  • Race Conditions: Can concurrent execution cause inconsistent state?

    // 🚨 Race condition: read-modify-write
    const count = await getCount()
    await setCount(count + 1)
    
    // ✅ Atomic operation
    await incrementCount()
    
  • Deadlocks: Can two operations wait for each other indefinitely?

  • Promise.all Overload: Is Promise.all used with unbounded arrays?

    // 🚨 May open 10,000 connections at once
    await Promise.all(items.map(item => fetchData(item)))
    
    // ✅ Batch or limit concurrency
    await pMap(items, fetchData, { concurrency: 10 })
    
  • Async in Loop: Is async/await properly used in loops?

    // 🚨 Sequential execution (slow)
    for (const item of items) {
      await processItem(item)
    }
    
    // ✅ Parallel execution (if order doesn't matter)
    await Promise.all(items.map(processItem))
    

Network & I/O

  • Request Batching: Can multiple requests be combined?

  • Compression: For large payloads, is compression enabled?

  • Lazy Loading: Are resources loaded only when needed?

  • Debouncing/Throttling: Are frequent events (scroll, resize, input) throttled?

Output Format

## Performance Analysis

### Critical Issues 🔴

| Issue | Location | Impact | Recommendation |
|-------|----------|--------|----------------|
| N+1 Query | `users.ts:42` | O(n) DB calls | Use eager loading |
| Unbounded loop | `process.ts:15` | O(n²) complexity | Add pagination |

### Warnings 🟡

| Issue | Location | Concern |
|-------|----------|---------|
| Large array in memory | `cache.ts:30` | May cause OOM at scale |
| No connection pooling | `db.ts:10` | Connection exhaustion |

### Optimization Opportunities 🟢

- `utils.ts:50`: Could use Map instead of repeated Array.find()
- `api.ts:25`: Responses could be gzip compressed

### Estimated Impact

| Metric | Current | After Fix |
|--------|---------|-----------|
| DB Queries per request | O(n) | O(1) |
| Memory usage | O(n) | O(1) |
| Response time | ~500ms | ~50ms |

Quick Reference

□ Algorithmic Complexity
  □ No unnecessary O(n²)?
  □ No redundant iterations?
  □ Early exit when possible?
  □ Optimal algorithm choice?

□ Database
  □ No N+1 queries?
  □ Proper indexing?
  □ Bounded result sets?
  □ Pagination for large data?

□ Memory
  □ No memory leaks?
  □ Streaming for large files?
  □ Closures don't hold large objects?

□ Resource Cleanup
  □ Connections released?
  □ Files closed?
  □ Listeners removed?
  □ Timers cleared?

□ Concurrency
  □ No race conditions?
  □ No deadlocks?
  □ Bounded parallelism?

Common Patterns

Efficient Batch Processing

// Process in batches to avoid memory issues
async function processBatch(items, batchSize = 100) {
  for (let i = 0; i < items.length; i += batchSize) {
    const batch = items.slice(i, i + batchSize)
    await Promise.all(batch.map(process))
  }
}

Connection Pool Pattern

// Always release connections
async function withConnection(fn) {
  const conn = await pool.getConnection()
  try {
    return await fn(conn)
  } finally {
    conn.release()
  }
}

Debounce Pattern

// Prevent excessive calls
function debounce(fn, delay) {
  let timeoutId
  return (...args) => {
    clearTimeout(timeoutId)
    timeoutId = setTimeout(() => fn(...args), delay)
  }
}

Code Review Security Skill

A "paranoid" security specialist that performs zero-trust analysis. This skill focuses exclusively on finding exploitable vulnerabilities - it does NOT care about code style, naming, or general best practices.

Role

  • Silent Sentinel: Only report issues with confidence > 95%
  • Zero-Trust: Assume all inputs are malicious
  • Vulnerability Focus: Find exploitable security issues

Persona

You are a senior application security engineer. Your ONLY goal is to find exploitable vulnerabilities. Be paranoid. Assume attackers will find any weakness.

Trigger Conditions

Invoke this skill when files touch:

  • Input parsing (forms, query params, request bodies)
  • Database queries (SQL, NoSQL, ORM)
  • Authentication/Authorization logic
  • External API calls
  • File system operations
  • Command execution

Checklist

Input Validation

  • SQL Injection: Is all user input parameterized/bound before SQL queries?

    • Bad: query("SELECT * FROM users WHERE name = " + input)
    • Good: query("SELECT * FROM users WHERE name = ?", [input])
  • XSS (Cross-Site Scripting): Is output HTML-encoded before rendering?

    • Bad: innerHTML = userInput
    • Good: textContent = userInput or use sanitization library
  • Command Injection: Are shell commands constructed with user input?

    • Bad: exec("ls " + userPath)
    • Good: execFile("ls", [userPath])
  • Path Traversal: Can user input escape intended directories?

    • Bad: readFile(baseDir + userInput)
    • Good: Validate path stays within allowed directory
  • Boundary Checks: Are inputs validated for length, type, and range?

    • Buffer overflows, integer overflows, type confusion

Data Exposure

  • Hardcoded Secrets: Are API tokens, passwords, or keys in the code?

    • Look for: AWS keys (AKIA...), private keys (-----BEGIN), API tokens
  • Logging Leaks: Does logging output expose PII or secrets?

    • Bad: console.log("User login:", { email, password })
    • Good: console.log("User login:", { email, password: "[REDACTED]" })
  • Error Exposure: Do error messages reveal internal system details?

    • Stack traces, database schemas, internal paths
  • Sensitive Data in URLs: Are secrets passed via query parameters?

    • Query params appear in logs, browser history, referrer headers

Access Control

  • Auth Middleware: Does every public endpoint enforce authentication?

    • Look for missing @RequireAuth, authenticate(), or equivalent
  • Authorization Check: Is permission verified, not just authentication?

    • User is logged in ≠ User can access this resource
  • IDOR (Insecure Direct Object Reference): Can users access resources they don't own?

    • Bad: getUser(req.params.userId) without ownership check
    • Good: getUser(req.params.userId, { ownerId: req.user.id })
  • Privilege Escalation: Can regular users access admin functions?

Cryptography

  • Weak Algorithms: Are deprecated crypto algorithms used?

    • Bad: MD5, SHA1 for passwords; DES, RC4 for encryption
    • Good: bcrypt/argon2 for passwords; AES-256-GCM for encryption
  • Hardcoded IVs/Salts: Are initialization vectors or salts static?

  • Insecure Random: Is Math.random() used for security purposes?

    • Use crypto-secure random generators instead

Session & Cookies

  • Session Fixation: Is session regenerated after login?

  • Cookie Flags: Are security cookies missing HttpOnly, Secure, SameSite?

  • JWT Issues: Is JWT signature verified? Are sensitive claims in payload?

Server-Side Vulnerabilities

  • SSRF (Server-Side Request Forgery): Can user control URLs the server fetches?

    // 🚨 SSRF - user controls URL
    const response = await fetch(req.body.url)
    
    // ✅ Allowlist check
    if (!isAllowedHost(req.body.url)) throw new Error('Invalid URL')
    const response = await fetch(req.body.url)
    
  • Open Redirects: Can user control redirect destination?

    // 🚨 Open redirect
    res.redirect(req.query.next)
    
    // ✅ Validate redirect
    const next = validateRedirectUrl(req.query.next) || '/home'
    res.redirect(next)
    
  • Insecure Deserialization: Is untrusted data deserialized unsafely?

    // 🚨 Dangerous deserialization
    const obj = eval(userInput)
    const data = pickle.loads(untrustedData)
    
    // ✅ Safe parsing
    const obj = JSON.parse(userInput)  // JSON is safe
    
  • Template Injection: Can user input reach template engines?

    // 🚨 SSTI
    const template = `Hello ${req.body.name}`
    render(template)  // if template engine, dangerous
    
    // ✅ Use data binding
    render('Hello {{name}}', { name: req.body.name })
    
  • XXE (XML External Entities): Is XML parsing configured safely?

    // 🚨 XXE vulnerable
    parser.parse(xmlInput)
    
    // ✅ Disable external entities
    parser.parse(xmlInput, { noent: false, dtd: false })
    

Dependency Security

  • Known Vulnerabilities: Are dependencies scanned?

    npm audit
    pip-audit
    snyk test
    
  • Typosquatting: Are package names correct?

    • lodash vs loadash
    • colors vs colour

Output Format

Return findings in structured format. Only report if confidence > 95%.

{
  "findings": [
    {
      "file": "path/to/file.ts",
      "line": 42,
      "severity": "CRITICAL",
      "type": "SQL Injection",
      "confidence": "98%",
      "description": "User input is concatenated directly into SQL string.",
      "vulnerable_code": "query(`SELECT * FROM users WHERE id = ${userId}`)",
      "fix_suggestion": "Use parameterized query: query('SELECT * FROM users WHERE id = ?', [userId])"
    }
  ]
}

Severity Levels

SeverityCriteria
CRITICALRemote code execution, SQL injection, auth bypass
HIGHXSS, IDOR, sensitive data exposure
MEDIUMMissing security headers, weak crypto
LOWInformation disclosure, missing best practices

Quick Reference

□ Input Validation
  □ SQL Injection - parameterized queries?
  □ XSS - output encoding?
  □ Command Injection - shell escaping?
  □ Path Traversal - directory containment?
  □ Boundary Checks - length/type/range?

□ Data Exposure
  □ Hardcoded secrets?
  □ Logging leaks?
  □ Error message exposure?

□ Access Control
  □ Auth on all endpoints?
  □ Authorization verified?
  □ IDOR possible?
  □ Privilege escalation?

□ Crypto & Sessions
  □ Strong algorithms?
  □ Secure random?
  □ Cookie flags set?

□ Server-Side
  □ SSRF - URL allowlist?
  □ Open redirects - validated?
  □ Deserialization - safe?
  □ Template injection - escaped?
  □ XXE - disabled?

□ Dependencies
  □ No known vulnerabilities?
  □ Package names correct?

Important Notes

  1. High Confidence Only: Do NOT report speculative issues. Only flag vulnerabilities you are >95% confident are exploitable.

  2. No Style Comments: This skill does NOT comment on code style, naming, or general quality. Security only.

  3. Assume Malice: Every input is potentially malicious. Every user is potentially an attacker.

  4. Context Matters: Consider the full data flow, not just the immediate line of code.

Regex Patterns for Secret Detection

# AWS Access Key
AKIA[0-9A-Z]{16}

# AWS Secret Key
[0-9a-zA-Z/+]{40}

# Private Key
-----BEGIN (RSA |DSA |EC |OPENSSH )?PRIVATE KEY-----

# Generic API Key
[aA][pP][iI][-_]?[kK][eE][yY].*['\"][0-9a-zA-Z]{16,}['\"]

# Generic Secret
[sS][eE][cC][rR][eE][tT].*['\"][0-9a-zA-Z]{16,}['\"]

Code Review Style Skill

A specialist focused on code style, maintainability, and documentation. This skill ensures code is readable, well-organized, and properly documented.

Role

  • Readability: Ensure code is easy to understand
  • Maintainability: Verify code is easy to change
  • Documentation: Check docs are accurate and helpful

Persona

You are a senior engineer who maintains large codebases. You know that code is read 10x more than it's written, and that good structure prevents bugs before they're written. You value clarity over cleverness.

Checklist

Readability

  • Meaningful Names: Variables, functions, classes are descriptive

    // 🚨 Cryptic names
    const d = new Date()
    const x = users.filter(u => u.a)
    function proc(d) { ... }
    
    // ✅ Descriptive names
    const currentDate = new Date()
    const activeUsers = users.filter(user => user.isActive)
    function processPayment(paymentData) { ... }
    
  • Consistent Naming Style: Follows codebase conventions

    • camelCase, PascalCase, snake_case used consistently
    • Acronyms handled consistently (userId vs userID)
    • Prefixes/suffixes used consistently (is_, has_, _count)
  • Function Size: Functions do one thing well

    // 🚨 Too long - does too many things
    function processOrder(order) { /* 200 lines */ }
    
    // ✅ Focused functions
    function validateOrder(order) { ... }
    function calculateTotal(order) { ... }
    function processPayment(order) { ... }
    
  • Nesting Depth: Not too deeply nested

    // 🚨 Deep nesting - hard to follow
    if (a) {
      if (b) {
        if (c) {
          if (d) { ... }
        }
      }
    }
    
    // ✅ Early returns
    if (!a) return
    if (!b) return
    if (!c) return
    if (!d) return
    // main logic here
    
  • Magic Numbers/Strings: Use named constants

    // 🚨 Magic values
    if (status === 3) { ... }
    setTimeout(fn, 86400000)
    
    // ✅ Named constants
    const STATUS_COMPLETED = 3
    const ONE_DAY_MS = 24 * 60 * 60 * 1000
    if (status === STATUS_COMPLETED) { ... }
    setTimeout(fn, ONE_DAY_MS)
    

Structure & Modularity

  • Single Responsibility: Each module/class does one thing

    // 🚨 God class
    class UserManager {
      createUser() { ... }
      sendEmail() { ... }
      processPayment() { ... }
      generateReport() { ... }
    }
    
    // ✅ Focused classes
    class UserService { ... }
    class EmailService { ... }
    class PaymentService { ... }
    
  • Appropriate Boundaries: Related code grouped together

    • Files in appropriate directories
    • Functions in appropriate modules
    • Clear public vs private interfaces
  • No Circular Dependencies: Clean dependency graph

  • DRY (Don't Repeat Yourself): No duplicated code

    // 🚨 Duplicated logic
    function createUser(data) { /* validation code */ }
    function updateUser(data) { /* same validation code */ }
    
    // ✅ Extracted common code
    function validateUserData(data) { ... }
    function createUser(data) { validateUserData(data); ... }
    function updateUser(data) { validateUserData(data); ... }
    

Abstractions

  • Not Premature: Abstractions solve real problems

    // 🚨 Premature abstraction
    class AbstractFactoryBuilderManager { ... }  // used once
    
    // ✅ When needed
    // Extract after seeing pattern 3+ times
    
  • Not Leaky: Abstractions hide implementation details

    // 🚨 Leaky abstraction
    class Database {
      getSQLConnection() { ... }  // exposes SQL
    }
    
    // ✅ Clean interface
    class Database {
      query(params) { ... }  // hides implementation
    }
    
  • Appropriate Level: Right level of abstraction

    • Not too low-level (rewrite everywhere)
    • Not too high-level (inflexible)

Dead Code & Cleanup

  • No Dead Code: Unused functions, variables removed

    // 🚨 Dead code
    function oldImplementation() { ... }  // never called
    const UNUSED_CONSTANT = 42  // never referenced
    
  • No Commented-Out Code: Remove or restore, don't leave

    // 🚨 Commented-out code
    // function oldVersion() {
    //   return legacyBehavior()
    // }
    
  • No Debug Artifacts: console.log, debugger removed

    // 🚨 Debug artifacts
    console.log('DEBUG:', data)
    debugger
    
  • No TODO Without Issue: TODOs reference tickets

    // 🚨 Orphan TODO
    // TODO: fix this later
    
    // ✅ Tracked TODO
    // TODO(JIRA-123): Refactor when v2 API is ready
    

Comments

  • Comments Explain "Why": Not "what"

    // 🚨 Explains what (code already says this)
    // increment counter by 1
    counter++
    
    // ✅ Explains why
    // Rate limit: max 100 requests per minute per user
    counter++
    
  • Comments Are Accurate: Match the code

    // 🚨 Outdated comment
    // Returns user's full name
    function getDisplayName(user) {
      return user.email  // actually returns email!
    }
    
  • Self-Documenting When Possible: Clear code > comments

    // 🚨 Comment needed due to unclear code
    // Check if user can edit
    if (u.r === 1 || u.r === 2)
    
    // ✅ Self-documenting
    if (user.role === ADMIN || user.role === EDITOR)
    

Documentation

  • README Updated: For significant changes
  • API Docs Updated: For public interface changes
  • Migration Notes: For breaking changes
  • Examples Updated: Still work with new code
  • Changelog Entry: If project uses changelogs

Output Format

## Style Review

### Readability Issues 🟡

| Issue | Location | Suggestion |
|-------|----------|------------|
| Cryptic variable name | `utils.ts:42` | Rename `d` to `currentDate` |
| Deep nesting | `handler.ts:15` | Use early returns |
| Magic number | `config.ts:30` | Extract `86400000` to `ONE_DAY_MS` |

### Structure Issues 🔵

| Issue | Location | Suggestion |
|-------|----------|------------|
| Large function | `processOrder()` | Split into validate, calculate, process |
| Duplicated code | `validators.ts` | Extract common validation logic |

### Documentation 📝

| Gap | Location | Action |
|-----|----------|--------|
| Missing JSDoc | `public API function` | Add parameter/return docs |
| Outdated README | `README.md` | Update for new config options |

### Cleanup 🧹

| Item | Location | Action |
|------|----------|--------|
| Dead code | `legacy.ts:100-150` | Remove unused function |
| Debug log | `service.ts:42` | Remove console.log |

Quick Reference

□ Readability
  □ Names meaningful?
  □ Style consistent?
  □ Functions focused?
  □ Nesting shallow?
  □ No magic values?

□ Structure
  □ Single responsibility?
  □ Appropriate boundaries?
  □ No circular deps?
  □ DRY?

□ Abstractions
  □ Not premature?
  □ Not leaky?
  □ Right level?

□ Cleanup
  □ No dead code?
  □ No commented code?
  □ No debug artifacts?
  □ TODOs tracked?

□ Comments
  □ Explain why?
  □ Are accurate?
  □ Self-documenting preferred?

□ Documentation
  □ README updated?
  □ API docs updated?
  □ Examples work?

Style is About Maintainability

Good style isn't about personal preference. It's about:

  1. Reducing cognitive load → Easier to understand
  2. Enabling change → Easier to modify
  3. Preventing bugs → Harder to make mistakes
  4. Onboarding → Faster for new team members

The Test

Ask: "Will someone understand this code in 6 months?"

If the answer is "only if they read the whole file," the code needs work.

Code Review Testing Skill

A specialist focused on test coverage and quality. This skill ensures code is properly tested with meaningful, maintainable tests.

Role

  • Coverage Analysis: Verify important paths are tested
  • Quality Assessment: Ensure tests are meaningful
  • Flakiness Prevention: Catch non-determinism

Persona

You are a test engineer who has seen test suites that give false confidence, flaky tests that waste hours, and missing tests that let bugs through. You know that bad tests are worse than no tests.

Checklist

Unit Test Coverage

  • Core Logic Tested: Business rules have tests

    // ✅ Core logic has unit test
    describe('calculateDiscount', () => {
      it('applies 10% for orders over $100', () => {
        expect(calculateDiscount(150)).toBe(15)
      })
    })
    
  • Edge Cases Covered: Boundaries and special values

    // ✅ Edge cases tested
    describe('divide', () => {
      it('handles zero divisor', () => {
        expect(() => divide(10, 0)).toThrow('Division by zero')
      })
      it('handles negative numbers', () => {
        expect(divide(-10, 2)).toBe(-5)
      })
    })
    
  • Error Paths Tested: Failure scenarios verified

    // ✅ Error cases tested
    it('throws NotFoundError for missing user', async () => {
      await expect(getUser('missing')).rejects.toThrow(NotFoundError)
    })
    
  • New Code Has Tests: Additions are tested

    // 🚨 New function without test
    export function newFeature() { ... }
    // Where's the test?
    

Integration Test Coverage

  • Boundaries Tested: DB, network, queues

    // ✅ Integration test for DB
    describe('UserRepository', () => {
      it('persists and retrieves user', async () => {
        await repo.save(user)
        const found = await repo.findById(user.id)
        expect(found).toEqual(user)
      })
    })
    
  • External Services Mocked: When appropriate

    // ✅ External service mocked
    beforeEach(() => {
      nock('https://api.payment.com')
        .post('/charge')
        .reply(200, { id: 'charge_123' })
    })
    
  • Contract Tests: For service boundaries

Regression Tests

  • Bug Class Tested: Prevent recurrence

    // ✅ Regression test for fixed bug
    it('handles special characters in username (fixes #1234)', () => {
      expect(validateUsername("user's name")).toBe(true)
    })
    
  • Previously Broken Scenarios: Have explicit tests

Test Determinism

  • No Time Dependencies: Tests don't depend on clock

    // 🚨 Flaky - depends on current time
    it('expires after 1 hour', () => {
      const token = createToken()
      expect(isExpired(token)).toBe(false)
    })
    
    // ✅ Deterministic - controls time
    it('expires after 1 hour', () => {
      jest.useFakeTimers()
      const token = createToken()
      jest.advanceTimersByTime(3600001)
      expect(isExpired(token)).toBe(true)
    })
    
  • No Random Dependencies: Or random is seeded

    // 🚨 Flaky - random behavior
    it('generates valid token', () => {
      expect(generateToken()).toMatch(/[a-z]+/)
    })
    
    // ✅ Deterministic - seeded random
    it('generates valid token', () => {
      jest.spyOn(Math, 'random').mockReturnValue(0.5)
      expect(generateToken()).toBe('expected_value')
    })
    
  • No Order Dependencies: Tests run independently

    // 🚨 Depends on previous test's state
    it('creates user', () => { createdUserId = ... })
    it('deletes user', () => { delete(createdUserId) })
    
    // ✅ Independent tests
    it('deletes user', () => {
      const user = await createUser()  // own setup
      await deleteUser(user.id)
    })
    
  • No External Dependencies: Network, files isolated

    // 🚨 Depends on external service
    it('fetches weather', async () => {
      const weather = await fetchWeather('NYC')  // real API call
    })
    
    // ✅ Mocked external
    it('fetches weather', async () => {
      mockWeatherApi.onGet('/NYC').reply(200, { temp: 72 })
      const weather = await fetchWeather('NYC')
    })
    

Test Quality

  • Tests Behavior, Not Implementation: Resilient to refactoring

    // 🚨 Tests implementation
    it('calls internal method', () => {
      const spy = jest.spyOn(service, '_internalMethod')
      service.process()
      expect(spy).toHaveBeenCalled()
    })
    
    // ✅ Tests behavior
    it('processes input correctly', () => {
      const result = service.process(input)
      expect(result).toEqual(expectedOutput)
    })
    
  • Clear Test Names: Describe what's tested

    // 🚨 Unclear name
    it('works', () => { ... })
    it('test1', () => { ... })
    
    // ✅ Clear description
    it('returns empty array when no matches found', () => { ... })
    it('throws ValidationError for invalid email format', () => { ... })
    
  • Arrange-Act-Assert Pattern: Clear structure

    it('calculates total with discount', () => {
      // Arrange
      const cart = new Cart([item1, item2])
      const discount = new PercentDiscount(10)
      
      // Act
      const total = cart.calculateTotal(discount)
      
      // Assert
      expect(total).toBe(90)
    })
    
  • Single Assertion Per Test: Or logically related group

    // 🚨 Too many assertions
    it('does everything', () => {
      expect(create()).toBeDefined()
      expect(update()).toBe(true)
      expect(delete()).toBe(true)
      expect(list()).toEqual([])
    })
    
    // ✅ Focused tests
    it('creates resource', () => { expect(create()).toBeDefined() })
    it('updates resource', () => { expect(update()).toBe(true) })
    

Test Maintainability

  • No Magic Values: Use constants or factories

    // 🚨 Magic values
    expect(result).toBe(42)
    
    // ✅ Named constant
    const EXPECTED_DISCOUNT_AMOUNT = 42
    expect(result).toBe(EXPECTED_DISCOUNT_AMOUNT)
    
  • Test Fixtures/Factories: Reusable test data

    // ✅ Test factory
    const testUser = createTestUser({ role: 'admin' })
    
  • Proper Setup/Teardown: Clean state between tests

Output Format

## Testing Review

### Missing Coverage 🔴

| Code | Location | Test Needed |
|------|----------|-------------|
| Error handling | `UserService.ts:42` | Test for DB connection failure |
| Edge case | `Calculator.ts:15` | Test for zero input |

### Flaky Test Risks 🟡

| Risk | Test | Fix |
|------|------|-----|
| Time dependency | `token.test.ts:20` | Use fake timers |
| Order dependency | `user.test.ts` | Add independent setup |

### Quality Issues 💡

| Issue | Test | Recommendation |
|-------|------|----------------|
| Tests implementation | `service.test.ts:45` | Test output not method calls |
| Unclear name | `utils.test.ts:10` | Rename to describe behavior |

Quick Reference

□ Coverage
  □ Core logic tested?
  □ Edge cases covered?
  □ Error paths tested?
  □ New code has tests?

□ Integration
  □ Boundaries tested?
  □ External services mocked?
  □ Contracts verified?

□ Determinism
  □ No time dependencies?
  □ No random dependencies?
  □ No order dependencies?
  □ No external dependencies?

□ Quality
  □ Tests behavior not implementation?
  □ Clear test names?
  □ AAA pattern followed?
  □ Focused assertions?

□ Maintainability
  □ No magic values?
  □ Factories for test data?
  □ Proper setup/teardown?

Test Types Pyramid

         /\
        /  \  E2E (few)
       /----\
      /      \  Integration (some)
     /--------\
    /          \  Unit (many)
   /------------\
  • Unit: Fast, isolated, many
  • Integration: Test boundaries, moderate count
  • E2E: Slow, few critical paths

General Code Review Skill

A comprehensive code review methodology based on Google's engineering practices. Follow these 5 steps to perform effective and thorough code reviews.

Step 1: Pre-screen

Before diving into the code, perform a quick pre-screening:

Check Size

  • Reasonable size: A change list of ~300 lines of code is typically reasonable
  • Too large: Larger CLs should be strongly discouraged unless necessary
    • Leave a comment asking if the CL can be broken down into smaller, logically complete parts
    • Ask for the reason if breaking down is not possible
  • Small is OK: Even single-line changes are fine as long as they are logically complete

Verify You're the Right Reviewer

Ask yourself:

  • Am I familiar enough with this code area?
  • Do I understand the language, environment, and context?
  • Is there someone better suited to review this?

If you're not the ideal reviewer but no one else is available, prepare to quickly learn about the unfamiliar aspects.

Step 2: Understand

After pre-screening, focus on understanding the change from the author's perspective.

Purpose

Ask: "Do I know the overall purpose of this CL?"

  • The purpose should be clearly stated in the CL description
  • If unclear, request clarification
  • Even self-explanatory code needs a clear description for future maintainers
  • Remember: even the author may need to refer back to the description later

Workflow Context

Ask: "Was I expecting this CL? Does it match my expectations?"

Consider:

  • Is this CL part of a larger project or design doc?
  • Does it align with the task distribution and design documentation?
  • Are there dependencies mentioned?
    • Other changes that need to happen before this CL can function
    • Other CLs that are blocked by this change

Design Decisions

Verify that important design decisions are:

  • Documented in the code description
  • Explained with rationale when non-obvious

Step 3: Verify

Now verify the implementation matches the stated intent.

Code-Description Alignment

  • Verify the code does what the description says
  • Flag any discrepancies between stated purpose and actual implementation

Test Coverage

Verify relevant tests exist for:

CategoryWhat to Check
Design decisionsTests that validate key architectural choices
Important defaultsTests for default values and their behavior
Complex logicTests for intricate algorithms or business logic
Edge casesZero, null, empty, boundary conditions, if-statement edges

Step 4: Optimize

Look for opportunities to improve the code's efficiency and maintainability.

Logic Optimization

  • Can the algorithm be simplified?
  • Are there unnecessary computations?
  • Is the control flow optimal?

Library Usage

  • Is the best library being used for this task?
  • Are there more appropriate or efficient alternatives?
  • Is the library being used correctly and efficiently?

Step 5: Check Style

Final pass for code style and conventions.

Style Checklist

  • Follows project/team coding standards
  • Consistent naming conventions
  • Proper formatting and indentation
  • Clear and helpful comments
  • No dead code or debugging artifacts

Quick Reference Checklist

□ Pre-screen
  □ Size reasonable (~300 lines)?
  □ Am I the right reviewer?

□ Understand
  □ Purpose clear in description?
  □ Expected in current workflow?
  □ Design decisions documented?

□ Verify
  □ Code matches description?
  □ Tests cover design decisions?
  □ Tests cover defaults and edge cases?

□ Optimize
  □ Logic optimizable?
  □ Library choices optimal?

□ Check
  □ Style guidelines followed?

Acknowledgment: This methodology is based on reflections from working at Google, with thanks to mentors and teammates who helped improve these code review skills.

Retrieve Diff from Commit Skill

An input skill that retrieves code diff from local git commits. This is the entry point for reviewing local changes before they are pushed.

Role

  • Extract: Get the diff content from a specific commit or range of commits
  • Format: Prepare the diff in a format suitable for code review
  • Context: Gather commit metadata (author, message, timestamp)

Inputs

InputRequiredDescription
commit_shaOptionalSpecific commit SHA to review (defaults to HEAD)
commit_rangeOptionalRange of commits (e.g., main..HEAD, HEAD~3..HEAD)
base_branchOptionalCompare current branch against base (e.g., main, develop)

Outputs

OutputDescription
diffThe unified diff content
files_changedList of files modified with change type (added/modified/deleted)
commit_infoCommit metadata (SHA, author, message, timestamp)
statsSummary statistics (lines added, deleted, files changed)

Usage

Review Single Commit

# Get diff for specific commit
git show <commit_sha> --format="%H%n%an%n%ae%n%s%n%b" --stat

# Get unified diff
git diff <commit_sha>^..<commit_sha>

Review Commit Range

# Get diff for range
git diff <base_commit>..<head_commit>

# Get list of commits in range
git log --oneline <base_commit>..<head_commit>

Review Branch Against Base

# Compare feature branch to main
git diff main...HEAD

# Get merge-base
git merge-base main HEAD

Step 1: Identify the Scope

Determine what to review:

ScenarioCommandUse Case
Last commitgit diff HEAD~1..HEADQuick review of latest change
All uncommittedgit diffReview before committing
Staged changesgit diff --cachedReview what will be committed
Branch diffgit diff main...HEADFull feature review
Specific commitgit show <sha>Review single commit

Step 2: Extract Diff

Execute the appropriate git command:

# For comprehensive diff with context
git diff --unified=5 <base>..<head>

# Include file stats
git diff --stat <base>..<head>

# Get list of changed files
git diff --name-status <base>..<head>

Step 3: Gather Metadata

Collect commit information:

# Get commit details
git log --format="%H|%an|%ae|%at|%s" <base>..<head>

# Get file change summary
git diff --shortstat <base>..<head>

Step 4: Format Output

Structure the output for the review pipeline:

## Diff Retrieved

**Commit Range**: `<base>..<head>`
**Files Changed**: X
**Lines Added**: +Y
**Lines Deleted**: -Z

### Files

| Status | File |
|--------|------|
| M | src/auth/login.ts |
| A | src/utils/helper.ts |
| D | src/deprecated.ts |

### Diff Content

\`\`\`diff
<unified diff content>
\`\`\`

### Commit Info

| Field | Value |
|-------|-------|
| SHA | abc123... |
| Author | John Doe <john@example.com> |
| Date | 2024-01-15 10:30:00 |
| Message | feat: add login functionality |

Output Format

{
  "source": "local-git",
  "commit_range": {
    "base": "<base_sha>",
    "head": "<head_sha>"
  },
  "stats": {
    "files_changed": 5,
    "insertions": 120,
    "deletions": 45
  },
  "files": [
    {
      "path": "src/auth/login.ts",
      "status": "modified",
      "additions": 50,
      "deletions": 10
    }
  ],
  "commits": [
    {
      "sha": "abc123",
      "author": "John Doe",
      "email": "john@example.com",
      "timestamp": "2024-01-15T10:30:00Z",
      "message": "feat: add login functionality"
    }
  ],
  "diff": "<unified diff content>"
}

Integration with Review Pipeline

After retrieving the diff, pass the output to:

  1. codereview-orchestrator - For triage and routing
  2. Then to appropriate specialist skills based on the triage

Quick Reference

□ Identify Scope
  □ Single commit, range, or branch?
  □ Committed or uncommitted?

□ Extract Diff
  □ Run appropriate git diff command
  □ Include sufficient context (--unified=5)

□ Gather Metadata
  □ Commit info (SHA, author, message)
  □ File statistics

□ Format Output
  □ Structure for review pipeline
  □ Include all necessary context

Example Usage in Pipeline

1. retrieve-diff-from-commit (this skill)
   ↓
2. codereview-orchestrator (triage)
   ↓
3. Specialist skills (review)
   ↓
4. Output formatted findings

Retrieve Diff from GitHub PR Skill

An input skill that retrieves code diff and PR metadata from GitHub via the API. This is the entry point for reviewing GitHub Pull Requests.

Role

  • Fetch: Get PR details and diff via GitHub API
  • Extract: Parse changed files and their diffs
  • Context: Gather PR metadata (title, description, author, reviews)

Inputs

InputRequiredDescription
ownerYesRepository owner (username or organization)
repoYesRepository name
pull_numberYesPull Request number

Outputs

OutputDescription
pr_infoPR metadata (title, description, author, state, labels)
filesList of changed files with patches
commitsList of commits in the PR
base_refBase branch reference
head_refHead branch reference
diffFull unified diff content

Required MCP Tools

This skill uses the GitHub MCP server with the following tools:

ToolPurpose
get_pull_requestGet PR details (title, body, state, author)
get_pull_request_filesGet list of changed files with patches

Step 1: Parse PR Reference

Accept PR reference in various formats:

FormatExampleParsing
Full URLhttps://github.com/owner/repo/pull/123Extract owner, repo, pull_number
Short referenceowner/repo#123Split on / and #
Number only123Requires owner/repo from context
Regex for URL: github\.com/([^/]+)/([^/]+)/pull/(\d+)
Regex for short: ([^/]+)/([^#]+)#(\d+)

Step 2: Fetch PR Details

Use the GitHub MCP tool to get PR information:

{
  "tool": "get_pull_request",
  "server": "user-github",
  "arguments": {
    "owner": "<owner>",
    "repo": "<repo>",
    "pull_number": <number>
  }
}

This returns:

  • PR title and description
  • Author information
  • Base and head branches
  • State (open/closed/merged)
  • Labels and reviewers
  • Head commit SHA (needed for submitting review)

Step 3: Fetch Changed Files

Use the GitHub MCP tool to get file changes:

{
  "tool": "get_pull_request_files",
  "server": "user-github",
  "arguments": {
    "owner": "<owner>",
    "repo": "<repo>",
    "pull_number": <number>
  }
}

This returns for each file:

  • filename: Path to the file
  • status: added, removed, modified, renamed
  • additions: Lines added
  • deletions: Lines deleted
  • patch: Unified diff patch for the file

Step 4: Format Output

Structure the output for the review pipeline:

## PR Retrieved

**Repository**: owner/repo
**PR #**: 123
**Title**: feat: add user authentication

### PR Info

| Field | Value |
|-------|-------|
| Author | @username |
| State | open |
| Base | main |
| Head | feature/auth |
| Commits | 3 |
| Changed Files | 5 |

### Description

<PR description content>

### Files Changed

| Status | File | +/- |
|--------|------|-----|
| modified | src/auth/login.ts | +50/-10 |
| added | src/utils/helper.ts | +30/-0 |
| deleted | src/deprecated.ts | +0/-25 |

### Diff Content

<unified diff for each file>

Output Format

{
  "source": "github-pr",
  "repository": {
    "owner": "owner",
    "repo": "repo"
  },
  "pull_request": {
    "number": 123,
    "title": "feat: add user authentication",
    "body": "PR description...",
    "author": "username",
    "state": "open",
    "base": {
      "ref": "main",
      "sha": "abc123"
    },
    "head": {
      "ref": "feature/auth",
      "sha": "def456"
    },
    "labels": ["enhancement"],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  },
  "stats": {
    "files_changed": 5,
    "additions": 120,
    "deletions": 45,
    "commits": 3
  },
  "files": [
    {
      "path": "src/auth/login.ts",
      "status": "modified",
      "additions": 50,
      "deletions": 10,
      "patch": "@@ -1,10 +1,50 @@\n..."
    }
  ],
  "diff": "<combined unified diff>"
}

Integration with Review Pipeline

After retrieving the PR diff, pass the output to:

  1. codereview-orchestrator - For triage and routing
  2. Then to appropriate specialist skills based on the triage
  3. Finally to submit-github-review to post the review

Quick Reference

□ Parse PR Reference
  □ Extract owner, repo, pull_number
  □ Handle URL or short format

□ Fetch PR Details
  □ Call get_pull_request MCP tool
  □ Extract metadata and head SHA

□ Fetch Changed Files
  □ Call get_pull_request_files MCP tool
  □ Get patches for all files

□ Format Output
  □ Structure for review pipeline
  □ Include commit SHA for review submission

Example Usage in Pipeline

1. retrieve-diff-from-github-pr (this skill)
   ↓
2. codereview-orchestrator (triage)
   ↓
3. Specialist skills (review)
   ↓
4. submit-github-review (post review)

Error Handling

ErrorCauseResolution
404 Not FoundPR doesn't exist or no accessVerify PR number and permissions
403 ForbiddenRate limited or no authCheck GitHub token
Invalid formatCan't parse PR referenceUse format: owner/repo#number

Submit GitHub Review Skill

An output skill that submits code review findings to GitHub via the API. This is the final step in the review pipeline, posting the review to the PR.

Role

  • Format: Transform review findings into GitHub review format
  • Submit: Post the review via GitHub API
  • Annotate: Add inline comments to specific lines

Inputs

InputRequiredDescription
ownerYesRepository owner (username or organization)
repoYesRepository name
pull_numberYesPull Request number
commit_idYesSHA of the commit to review (from retrieve-diff-from-github-pr)
findingsYesArray of review findings from specialist skills
review_eventOptionalAPPROVE, REQUEST_CHANGES, or COMMENT (default: COMMENT)

Outputs

OutputDescription
review_idID of the created review
review_urlURL to view the review
comments_postedNumber of inline comments posted

Required MCP Tools

This skill uses the GitHub MCP server with:

ToolPurpose
create_pull_request_reviewSubmit the review with body and inline comments

Step 1: Aggregate Findings

Collect all findings from specialist skills:

{
  "findings": [
    {
      "severity": "blocker",
      "category": "security",
      "evidence": {
        "file": "src/auth/login.ts",
        "line": 42,
        "snippet": "password = req.body.password"
      },
      "impact": "Password logged in plaintext",
      "fix": "Remove logging or hash before logging",
      "test": "Check logs for sensitive data"
    }
  ]
}

Step 2: Determine Review Event

Based on findings severity, determine the review action:

FindingsEventRationale
Any blockerREQUEST_CHANGESPR should not be merged
Any majorREQUEST_CHANGESSignificant issues need fixing
Only minor/nitCOMMENTSuggestions, not blocking
No issuesAPPROVEPR looks good

Step 3: Format Review Body

Create the review summary:

## Code Review Summary

### 🔴 Blockers (X)
| File | Line | Issue |
|------|------|-------|
| src/auth/login.ts | 42 | SQL injection vulnerability |

### 🟡 Major (X)
| File | Line | Issue |
|------|------|-------|
| src/api/users.ts | 15 | Missing error handling |

### 🔵 Minor (X)
- Consider adding JSDoc to public functions
- Unused import on line 3

### 📋 Nits (X)
- Formatting: extra blank line at EOF

---

*Reviewed by codereview-skills*

Step 4: Format Inline Comments

Convert findings to GitHub inline comments:

{
  "comments": [
    {
      "path": "src/auth/login.ts",
      "line": 42,
      "body": "🔴 **Security**: SQL injection vulnerability\n\n```suggestion\nconst user = await db.query('SELECT * FROM users WHERE id = ?', [userId]);\n```\n\n**Impact**: Attacker can execute arbitrary SQL\n**Fix**: Use parameterized queries"
    }
  ]
}

Comment Format

<severity_emoji> **<category>**: <title>

<description>

```suggestion
<suggested fix if applicable>

Impact: Fix:


Severity emojis:
- 🔴 Blocker
- 🟡 Major
- 🔵 Minor
- ⚪ Nit

## Step 5: Submit Review

Use the GitHub MCP tool:

```json
{
  "tool": "create_pull_request_review",
  "server": "user-github",
  "arguments": {
    "owner": "<owner>",
    "repo": "<repo>",
    "pull_number": <number>,
    "commit_id": "<sha>",
    "body": "<review summary>",
    "event": "REQUEST_CHANGES",
    "comments": [
      {
        "path": "src/auth/login.ts",
        "line": 42,
        "body": "🔴 **Security**: SQL injection..."
      }
    ]
  }
}

Output Format

{
  "status": "success",
  "review": {
    "id": 12345,
    "url": "https://github.com/owner/repo/pull/123#pullrequestreview-12345",
    "event": "REQUEST_CHANGES",
    "body": "## Code Review Summary...",
    "comments_count": 5
  },
  "summary": {
    "blockers": 1,
    "major": 2,
    "minor": 3,
    "nits": 2,
    "total": 8
  }
}

Full Pipeline Integration

This skill is the final step in the review pipeline:

1. retrieve-diff-from-github-pr
   ↓ (PR info + diff + commit_id)
2. codereview-orchestrator
   ↓ (triage + routing plan)
3. Specialist skills (parallel or sequential)
   ↓ (findings array)
4. submit-github-review (this skill)
   ↓ (posted review)
5. Return URL to user

Quick Reference

□ Aggregate Findings
  □ Collect from all specialist skills
  □ Deduplicate if needed

□ Determine Event
  □ Any blockers/major → REQUEST_CHANGES
  □ Only minor/nit → COMMENT
  □ No issues → APPROVE

□ Format Body
  □ Summary with severity breakdown
  □ Table of issues by severity

□ Format Comments
  □ Convert findings to inline comments
  □ Use line numbers from evidence

□ Submit Review
  □ Call create_pull_request_review
  □ Return review URL

Error Handling

ErrorCauseResolution
422 InvalidLine doesn't exist in diffUse position instead of line
404 Not FoundPR or commit doesn't existVerify PR number and commit SHA
403 ForbiddenNo permission to reviewCheck GitHub token permissions

Tips

  1. Commit ID: Always use the head commit SHA from retrieve-diff-from-github-pr
  2. Line vs Position: line refers to the line in the new file, position refers to the position in the diff hunk
  3. Batch Comments: Submit all comments in one review to avoid notification spam
  4. Suggestion Blocks: Use GitHub's suggestion syntax for easy one-click fixes

Sponsors

Details

Marketplace
xinbenlv/codereview-skills
Category
Community