# Project Code Review

Checks changed code for missing tests, dead code, type and lint issues.

- Repository: https://github.com/vectorize-io/hindsight (57678 stars)
- Category: Git and review
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add vectorize-io/hindsight --skill code-review -g -a claude-code -y`
Codex: `npx skills add vectorize-io/hindsight --skill code-review -g -a codex -y`
Cursor: `npx skills add vectorize-io/hindsight --skill code-review -g -a cursor -y`
Gemini CLI: `npx skills add vectorize-io/hindsight --skill code-review -g -a gemini-cli -y`

## Description

Review changed code against project standards. Checks for missing tests, dead code, type safety, lint issues, and coding conventions. Run after completing any implementation work.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Code Review

Review all changed code against the project's quality standards and coding conventions.

## Code Standards

Read and internalize these standards before writing code. The review steps below verify compliance.

### Supported interpreters

**CPython 3.11** is the baseline, what `docker/standalone/Dockerfile` ships, and what
the `.python-version` pin and `uv.lock` resolve for. The package supports 3.11 through
3.14; `build-api-python-versions` in CI installs and smoke-tests each of them, so a
dependency floor that excludes one of those interpreters is a break, not a follow-up.

### Python Style
- Python 3.11+, type hints required, and see Supported interpreters above
- Async throughout (asyncpg, async FastAPI)
- Pydantic models for request/response
- Ruff for linting (line-length 120)
- No Python files at project root - maintain clean directory structure
- **Never use multi-item tuple return values**, not even for internal/private functions. Always use a dataclass or Pydantic model. No exceptions, no "it's just two values" shortcuts. If a function returns more than one value, define a named type for it.

### Type Safety with Pydantic Models
**NEVER use raw `dict` types for structured data**, this applies to all code, including internal helpers and private functions. If the dict has known keys, it must be a dataclass or Pydantic model:
- Use Pydantic `BaseModel` for all data structures passed between functions
- Use `@dataclass` for lightweight internal data containers when Pydantic validation isn't needed
- Add `@field_validator` for type coercion (e.g., ensuring datetimes are timezone-aware)
- Avoid `dict.get()` patterns - use typed model attributes instead
- Parse external data (JSON, API responses) into Pydantic models at the boundary
- This catches type errors at parse time, not deep in business logic
- The only acceptable `dict` usage is for truly dynamic/unknown keys (e.g., arbitrary metadata, JSON blobs with no fixed schema)

The rest: https://github.com/vectorize-io/hindsight/blob/HEAD/.claude/skills/code-review/SKILL.md