Reviewing Source Code Changes Skill

Reviewing Source Code Changes

Guide for reviewing PRs and source code changes in /library/src/.

When to Use This Guide

Reviewing pull requests modifying library source
Validating implementation patterns before merging
Checking code quality, types, documentation, and tests

Review Process

Understand the change — Read PR description, identify affected files
Check patterns — Verify code follows existing conventions
Verify types — Ensure type safety and proper inference
Review docs — Confirm JSDoc is complete and accurate
Check tests — Validate runtime and type test coverage

What to Review

Code Quality

| Check | Requirement | | ----------------- | --------------------------------------------------------------------- | | Naming | Matches existing patterns (StringSchema, minLength, _parse) | | Purity annotation | // @__NO_SIDE_EFFECTS__ before pure factory functions | | Import extensions | All imports use .ts extension | | Interface vs type | Use interface for object shapes, type for unions/aliases | | Folder structure | Each API has: name.ts, name.test.ts, name.test-d.ts, index.ts |

Good — purity annotation:

// @__NO_SIDE_EFFECTS__
export function string(message?: ErrorMessage<StringIssue>): StringSchema {
  return {
    /* ... */
  };
}

Bad — missing annotation:

export function string(message?: ErrorMessage<StringIssue>): StringSchema {
  return {
    /* ... */
  };
}

Type Safety

| Check | Requirement | | ----------------- | ----------------------------------------------------- | | Generic inference | Types infer correctly without explicit annotations | | Constraints | Generic parameters have appropriate extends clauses | | Return types | Explicit return types on exported functions | | Type tests | .test-d.ts file covers type inference scenarios |

Good — constrained generic:

export function minLength<
  TInput extends LengthInput,
  TRequirement extends number,
>(
  requirement: TRequirement,
  message?: ErrorMessage<MinLengthIssue<TInput, TRequirement>>
): MinLengthAction<TInput, TRequirement>;

Documentation

| Check | Requirement | | -------------- | ------------------------------------------------- | | JSDoc present | All exported functions have JSDoc | | First line | Action verb matching function purpose (see below) | | @param tags | Every parameter documented | | @returns tag | Return value documented | | Overloads | Every overload has its own complete JSDoc block |

First line patterns by category:

| Category | Pattern | | -------------- | ---------------------------------------------- | | Schemas | Creates a ... schema. | | Actions | Creates a ... action. | | Parse methods | Parses ... | | Type guards | Checks if ... | | Unwrap methods | Unwraps ... | | Other methods | Creates a ..., Returns ..., Forwards ... |

See repo-source-code-document skill for full documentation rules.

Tests

| Check | Requirement | | -------------- | ---------------------------------------------------------- | | Runtime tests | .test.ts covers success cases, failure cases, edge cases | | Type tests | .test-d.ts validates type inference with expectTypeOf | | Issue messages | Tests verify correct error messages and issue structure |

Common Issues

| Issue | What to Look For | | ------------------------- | ------------------------------------------------------------ | | Missing purity annotation | Factory function without // @__NO_SIDE_EFFECTS__ | | Incomplete JSDoc | Missing @param or @returns, wrong description format | | No type tests | New API without .test-d.ts file | | Wrong import extension | Imports without .ts suffix | | Inconsistent naming | Schema not ending in Schema, action not ending in Action | | Side effects in pure code | Mutations, I/O, or global state in schema/action creation |

Checklist

[ ] Implementation follows existing patterns in similar files
[ ] // @__NO_SIDE_EFFECTS__ on pure factory functions
[ ] All imports use .ts extension
[ ] interface used for object shapes
[ ] JSDoc complete on all exports
[ ] Runtime tests in .test.ts
[ ] Type tests in .test-d.ts
[ ] Naming conventions followed

Related Skills

repo-structure-navigate — Navigate the codebase
repo-source-code-document — JSDoc requirements

Agent Skills: Reviewing Source Code Changes

Install this agent skill to your local

Skill Files