Skip to content

ilandahan/AID / skills/code-review

code-review

Unverified

Comprehensive code review for commits and pull requests. Covers security, TDD, code quality, and documentation standards.

Code Review Skill

Review in this order, stopping only to record findings:

Code Changes -> Security Scan (P1) -> TDD Validation (P2) -> Code Quality -> Verdict

Deep examples live in references/. Do not re-derive them here:

  • references/security-patterns.md - per-language vulnerable/safe pairs
  • references/tdd-patterns.md - TDD process + test quality examples
  • references/review-templates.md - copy-paste review templates
  • references/iso27001-guidelines.md - compliance checklist
  • references/validation-false-positives.md - anti-patterns when reviewing validation/audit code

Security Checklist (Critical)

OWASP Top 10

VulnerabilityRed Flag
InjectionString concatenation in queries
Broken AuthPlain text passwords, weak tokens
Sensitive Data ExposureSecrets in logs
XSSinnerHTML, dangerouslySetInnerHTML
Broken Access ControlMissing permission checks

Security Code Patterns

RiskBADGOOD
SQL Injectionconst query = `SELECT * FROM users WHERE id = ${userId}`;const query = 'SELECT * FROM users WHERE id = ?'; db.query(query, [userId]);
XSSelement.innerHTML = userInput;element.textContent = userInput;
Command injectionexec(`ls ${userPath}`);fs.readdir(userPath);
Hardcoded secretsReal credentials embedded in source codeSupply production credentials through secure runtime configuration, never committed literals. Documentation uses only fake placeholders such as YOUR_API_KEY.

Security Review Questions

  • ALL user input validated/sanitized?
  • Queries parameterized?
  • Secrets in environment variables?
  • Auth checked on protected routes?
  • Error messages safe (no stack traces)?

TDD Checklist (Priority)

QuestionExpectedRed Flag
Tests written first?YesImplementation without tests
Tests define behavior?WHAT not HOWInternal implementation tested
Coverage adequate?Critical paths coveredOnly happy path
Tests independent?Run in isolationOrder-dependent

Test Quality Patterns

RuleBADGOOD
Test behavior, not internalsjest.spyOn(service, '_privateMethod') then expect(spy).toHaveBeenCalled() (HOW)const result = service.doThing(); expect(result).toEqual(expectedOutput); (WHAT)
Realistic test dataconst mockUser = { id: 1, name: 'test' };const mockUser = { id: 'usr_abc123', name: 'Jane Smith', email: 'jane@example.com', createdAt: new Date('2024-01-15'), roles: ['user', 'admin'] };
Cover edge cases, not just happy pathonly test('creates user', ...)plus throws on missing email, throws on duplicate username, handles unicode names

Code Quality Checklists

No Shortcuts

PatternProblem
catch (e) { }Silent exception
TODO, FIXME, HACKIncomplete work
Commented-out codeDead code
any overuseType safety bypassed

No Hardcoded Values

BadGood
if (status === 3)if (status === Status.APPROVED)
setTimeout(fn, 5000)setTimeout(fn, TIMEOUT_MS)
'http://localhost:3000'process.env.API_URL

Root Cause Fixes

Symptom Fix (Bad)Root Cause Fix (Good)
Add null check where crash occursValidate data at entry point
Retry failed request 3 timesFix why request fails
Catch and ignore errorHandle error appropriately
Add delay to avoid race conditionFix the race condition

Documentation (Mandatory)

LevelRequired
File@file, @description, @related
ClassPurpose, responsibilities
Function@param, @returns, @throws
// BAD: No documentation
export function createUser(data) {
  return db.create(data);
}

// GOOD: Full documentation
/**
 * Creates a new user account with validation.
 *
 * @param data - User creation input
 * @returns Created user object
 * @throws {ValidationError} If email invalid
 *
 * @related
 *   - ./UserRepository.ts - Database persistence
 *   - ../validators/email.ts - Email validation
 */
export async function createUser(data: CreateUserInput): Promise<User>

Red Flags

FlagSeverityAction
SQL/Command injectionCRITICALBlock
Hardcoded secretsCRITICALBlock
XSS vulnerabilityCRITICALBlock
No tests for new codeMAJORRequest tests
Tests modified to passMAJORInvestigate
Silent exception catchMAJORRequire logging
Missing file headerMAJORAdd docs

Output Format

# Code Review: [Branch/PR]

## Summary
| Metric | Value |
|--------|-------|
| Files reviewed | X |
| Security issues | X (Y critical) |
| TDD compliance | Y/N |
| Verdict | Ready/Review/Rework |

## Security Issues
### Critical
1. **[Type]** - `file:line`
   - Problem: [desc]
   - Impact: [potential damage]
   - Fix: [solution]

## TDD Issues
1. **[Issue]** - `file:line`
   - Fix: [tests to add]

## Code Quality Issues
[issues]

## Verdict
[decision + reasoning]

### Required Before Merge
- [ ] [action item]

Review Workflow

Step 1: Security Scan First

# Check for secrets
grep -r "password\|secret\|api_key\|token" --include="*.ts"

# Check for SQL injection
grep -r "SELECT.*\${" --include="*.ts"

# Check for XSS
grep -r "innerHTML\|dangerouslySetInnerHTML" --include="*.tsx"

Step 2: TDD Validation

# Check test coverage
npm test -- --coverage

# Verify tests exist for changed files

Verdict Rules

ConditionVerdict
Any critical securityNeeds Rework
No tests for new functionalityNeeds Review
Minor issues onlyReady (with suggestions)
No issuesReady to merge

Example: Transparency Block

<decision-transparency>
**Decision:** Approve with minor suggestions (Ready)

**Reasoning:**
- **Security**: No vulnerabilities found
- **Testing**: All new code has tests
- **Quality**: Minor naming suggestions only

**Issues Found:**
1. Minor: Variable name `d` could be `data` (line 42)
2. Minor: Consider extracting magic number 5 to constant

**Confidence:** High - Standard approval scenario
</decision-transparency>

Example: Debate Invitation

<debate-invitation>
**Topic:** Handling of deprecated API usage

**Option A: Block Until Fixed**
- Pros: No technical debt
- Cons: Delays release

**Option B: Approve with Follow-up Task**
- Pros: Pragmatic, allows progress
- Cons: Debt may linger

**My Lean:** Option B - Create ticket, set deadline

**Your Input Needed:** Is there a release deadline? How critical is this code path?
</debate-invitation>
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall