contextual-review

name	contextual-review
description	Review pull requests for code quality, security vulnerabilities, best practices, and potential issues. Use when reviewing PRs, examining diffs, or providing code review feedback.

Contextual Review

Perform comprehensive reviews of code changes, implementation plans, and architecture decisions. Analyzes for quality, correctness, security, and adherence to project standards.

First: Read the Base Guidelines

Before reviewing any code, read base-review.md. It establishes:

• Reviewer philosophy (respect existing patterns, burden of proof on changes)
• Core quality standards (type safety, transaction integrity, data access, caching)
• Severity calibration with codebase-specific examples
• Common blind spots that reviewers unfamiliar with this codebase miss

The base guidelines apply to ALL reviews. Area-specific guides add targeted checklists.

When to Use

• Reviewing pull request changes
• Examining workspace diffs before creating a PR
• Getting feedback on code changes
• Identifying potential issues before merging
• Reviewing gameplans and implementation plans before execution
• Validating data model and API design decisions

Area-Specific Guidelines

Based on what files changed, consult the appropriate reference:

Changed Files	Reference
platform/docs/	docs-review.md - Documentation review guidelines
platform/flowglad-next/src/db/schema/, openapi.json, api-contract/	api-review.md - Data model and API review
packages/	packages-review.md - SDK package review
playground/	playground-review.md - Example project review
platform/flowglad-next/	platform-review.md - Main platform review

For reviewing implementation plans before code is written:

Review Type	Reference
Gameplans / Implementation Plans	gameplan-review.md - Pre-implementation plan review

Read the relevant reference file(s) based on the diff to get area-specific checklists and guidelines.

Review Process

0. Checkout PR

Run gh pr checkout <PR> to get the PR code locally. If it fails, continue with the review.

1. Gather Context

First, understand the scope of changes:

# Get the diff statistics to understand what files changed
GetWorkspaceDiff with stat: true

# Then examine individual file changes
GetWorkspaceDiff with file: 'path/to/file'

2. Review Categories

Analyze changes across these dimensions:

Category	Focus Areas
Correctness	Logic errors, edge cases, null handling, off-by-one errors
Security	Input validation, injection risks, auth/authz, secrets exposure
Performance	N+1 queries, unnecessary loops, missing indexes, memory leaks
Maintainability	Code clarity, naming, DRY violations, complexity
Testing	Test coverage, edge cases tested, test quality
Types	Type safety, proper typing, avoiding any

3. Project-Specific Checks

For this codebase, also verify:

• Bun: Using bun instead of npm or yarn
• Drizzle ORM: Schema changes use migrations:generate, never manual migrations
• Testing Guidelines:
  • No mocking unless for network calls
  • No .spyOn or dynamic imports
  • No any types in tests
  • Each it block should have specific assertions, not toBeDefined
  • One scenario per it with exhaustive assertions
• Security: Check OWASP top 10 vulnerabilities (XSS, injection, etc.)

4. Provide Feedback

Use the DiffComment tool to leave targeted feedback:

DiffComment({
  comments: [
    {
      file: "path/to/file.ts",
      lineNumber: 42,
      body: "Potential SQL injection vulnerability. Consider using parameterized queries."
    }
  ]
})

Review Checklist

Code Quality

• Clear, descriptive variable and function names
• Functions are focused and not too long
• No dead code or commented-out code
• Error handling is appropriate
• Edge cases are handled

Security

• No hardcoded secrets or credentials
• Input is validated and sanitized
• No SQL injection vectors
• No XSS vulnerabilities
• Authentication/authorization is correct
• Sensitive data is not logged

Performance

• No unnecessary database queries
• Appropriate use of indexes
• No obvious memory leaks
• Pagination for large datasets
• Caching where appropriate

Testing

• New code has tests
• Tests cover happy path and error cases
• Tests are meaningful, not just for coverage
• No flaky test patterns

TypeScript

• Proper types used (no any without justification)
• Type narrowing is correct
• Generic types are appropriate
• Null/undefined handled properly

Output Format

Provide a structured review with:

1. Summary: Brief overview of what the PR does
2. Findings: Categorized issues (Critical, High, Medium, Low, Suggestions)
3. Positive Notes: Good patterns or improvements noticed
4. Recommendation: Approve, Request Changes, or Comment

Severity Levels

• Critical: Security vulnerabilities, data loss risks, breaking changes
• High: Bugs, significant performance issues, missing error handling
• Medium: Code quality issues, missing tests, unclear logic
• Low: Style issues, minor improvements, nitpicks
• Suggestion: Optional improvements, alternative approaches

Example Review

## Summary
This PR adds user authentication using JWT tokens with refresh token support.

## Findings

### Critical
- **src/auth/token.ts:45**: JWT secret is hardcoded. Move to environment variable.

### High
- **src/auth/login.ts:23**: Missing rate limiting on login endpoint.

### Medium
- **src/auth/validate.ts:12**: Token expiration check should use `<=` not `<` to handle exact expiration time.

### Suggestions
- Consider adding request ID to auth logs for debugging.

## Positive Notes
- Good separation of concerns between token generation and validation
- Comprehensive error types for different auth failures

## Recommendation
**Request Changes** - Address the critical security issue before merging.

Workflow

1. Attempt to checkout the PR with gh pr checkout <PR> (continue if it fails)
2. Get diff statistics with GetWorkspaceDiff(stat: true)
3. Review changed files systematically
4. Use DiffComment for inline feedback
5. Provide overall summary and recommendation
6. Offer to help fix any critical issues