code-review-checklist

name	code-review-checklist
description	Apply layer-specific quality checklists for Python ETL, Airflow DAGs, dbt models, SQL, FastAPI, Vue.js, and Docker Compose changes in the HH data platform.
license	MIT
compatibility	opencode
metadata	{"audience":"code-reviewer","domain":"quality"}

What I do

Provide a structured, layer-specific checklist so no critical concern is missed during a code review. Apply the relevant sections based on which files changed.

---

Python / ETL (src/, apps/api/)

• Extraction, transformation, and persistence are in separate functions or modules.
• No hardcoded credentials, tokens, or API keys anywhere in the file.
• Error handling and logging are present for all external calls (HTTP, DB).
• Functions are small, named clearly, and testable in isolation.
• Extra dependencies are justified; prefer the standard library where sufficient.
• Public interfaces have type hints.
• No print() used for operational output — use logging.

---

Airflow DAGs (dags/)

• DAG is idempotent and safe to re-run without duplicating or losing data.
• owner, retries, and retry_delay are defined on the default args.
• schedule_interval / schedule is set intentionally and documented in a comment.
• No business or transformation logic inside the DAG file — it belongs in src/.
• Dynamic task mapping reads from database state, not from inline literals.
• Connections, API keys, and variables use Airflow secrets backend or environment variables — no hardcoded values.
• Task IDs are descriptive and stable (renaming them breaks existing runs).

---

dbt (dbt/)

• Staging models cast key analytical fields to appropriate types.
• No SELECT * in staging or mart models unless explicitly justified in a comment.
• Business logic is in mart models, not in staging.
• Model names follow the convention: stg_hh_* for staging, mart_hh_* for marts.
• Grain and deduplication rules are documented in model description or spec.
• All table/view references use {{ ref() }} or {{ source() }} macros — no raw SQL names.
• Removed or renamed models have corresponding downstream dependency checks.

---

SQL (sql/)

• DDL includes a primary key or unique constraint on the natural identifier.
• Ingestion metadata columns are present: ingested_at, loaded_at, or updated_at.
• Scripts are safe to run multiple times (IF NOT EXISTS, ON CONFLICT DO UPDATE / NOTHING).
• Upsert keys match the deduplication rules defined in the relevant spec.
• No sensitive or PII data stored in plain-text columns without explicit justification.
• Column names are snake_case and descriptive.

---

FastAPI / asyncio (apps/api/)

• All route handlers are async; no blocking IO on the event loop (no requests, no synchronous DB calls).
• Request and response models use explicit Pydantic schemas — no raw dict returns.
• Business logic is not duplicated from the warehouse inside handlers.
• Freshness, pagination, and filter semantics are explicit in each endpoint contract.
• Database sessions and connections are properly closed (context manager or finally).
• API response schemas match the contracts in docs/specs/.

---

Vue.js / Frontend (apps/web/)

• No raw API base URLs hardcoded — use config constants or environment variables.
• Empty states and error states are handled and visible to the user.
• Components have a single clear responsibility; large components are split.
• No sensitive data rendered unexpectedly into the DOM or console.
• API calls include error handling (.catch or try/catch).

---

Docker Compose / Infrastructure (docker-compose.yml, .env*)

• No secrets or tokens committed to docker-compose.yml or any .env file tracked by git.
• .env.example is updated whenever a new environment variable is introduced.
• Health checks are defined for stateful services (PostgreSQL, Airflow).
• Volume mounts are intentional and documented with a comment if non-obvious.
• Service dependencies and startup order (depends_on) are explicit.

---

Documentation (docs/specs/, AGENTS.md, README.md)

• docs/specs/ is updated if data contracts, interfaces, or layer responsibilities changed.
• AGENTS.md reflects any new architecture rule or structural change.
• README.md is updated if setup steps, commands, or repo structure changed.
• New specs are short, concrete, and directly usable by engineers (prefer tables and bullets over prose).

---

Cross-cutting (always check)

• No secrets in any committed file (grep for password, token, secret, api_key).
• No debug code left in (print, breakpoint, pdb, console.log).
• Files touched but not part of the change are not accidentally modified.