atelier/review/agent-checklist.md

# Agent Pre-Completion Checklist

> Every AI agent runs this checklist before completing a task. If any item fails, fix it before finishing. This is the gate between "the code is written" and "the task is done."

## How to Use This

1. Read the relevant `domains/<x>/first-principles.md` before starting the task.
2. Implement the task.
3. Run this checklist. Every item must pass (or be explicitly justified).
4. If an item fails, fix it. Do not "skip" without a written reason.

## Core Principles Checklist (C1–C8)

### C1 Correctness
- [ ] Does the code do what the task asked, completely?
- [ ] Does it handle the specified edge cases? (nulls, empties, max, min)
- [ ] Does it handle the failure cases? (errors, timeouts, invalid input)
- [ ] Is there a test that would fail if the code were wrong?

### C2 Clarity
- [ ] Can a stranger read this and understand it without asking you?
- [ ] Are names intent-revealing? (No `data`, `temp`, `x`, `doStuff`)
- [ ] Do comments explain *why*, not *what*?
- [ ] Is the structure scannable? (Short functions, clear sections)

### C3 Simplicity
- [ ] Is this the simplest solution that is complete?
- [ ] Is there dead code? (Unreachable branches, unused variables)
- [ ] Is there premature abstraction? (An interface with one implementation)
- [ ] Could 50 lines do what 200 lines do?

### C4 Locality
- [ ] Does related logic live together?
- [ ] Are side effects near their causes?
- [ ] Does a change to this feature require touching distant files?

### C5 Reversibility
- [ ] Is this change undoable? (migration has a `down`, deploy has a rollback)
- [ ] Did I avoid irreversible actions without explicit confirmation?
- [ ] Is state recoverable? (Can the user get back to where they were?)

### C6 Composability
- [ ] Does this component/function do one thing?
- [ ] Is the boundary (props/args/return) explicit and typed?
- [ ] Can this be reused in a new context without modification?

### C7 Observability
- [ ] Are there logs for significant events?
- [ ] Do errors carry enough context to debug? (request ID, user, action)
- [ ] Are there metrics for the operation? (count, latency)
- [ ] Are there no secrets in logs?

### C8 Economy
- [ ] Is memory bounded? (No unbounded growth, no loading everything)
- [ ] Is time bounded? (No N+1, no blocking without timeout)
- [ ] Are resources released? (file handles, connections, locks)

## Domain-Specific Triggers

If the task touches a domain, run that domain's checklist:

### If UI/UX (see `domains/uiux/`)
- [ ] Every interactive element is keyboard-reachable
- [ ] Every image has alt text (or marked decorative)
- [ ] Every form control has a label
- [ ] Focus is visible
- [ ] No color-only information
- [ ] Components use design tokens, not raw values

### If API (see `domains/api/`)
- [ ] Endpoints are nouns, plural, lowercase-hyphenated
- [ ] Status codes are correct (200/201/204/4xx/5xx per semantics)
- [ ] Errors are structured (code, message, request_id)
- [ ] Input is validated against a schema
- [ ] Auth is required by default

### If Security (see `domains/security/`)
- [ ] No secrets in code, logs, URLs, or error messages
- [ ] Input is validated at the boundary
- [ ] Output is encoded for its context
- [ ] Crypto uses vetted libraries (no MD5/SHA1 for security)
- [ ] Authorization is checked, not assumed

### If Data (see `domains/data/`)
- [ ] Schema reflects the domain (not the application)
- [ ] Constraints are in the schema (NOT NULL, UNIQUE, FK)
- [ ] Migration has an `up` and a `down`
- [ ] Types are domain-accurate (UUID, TIMESTAMPTZ, DECIMAL for money)
- [ ] No `SELECT *`; no N+1

### If Testing (see `domains/testing/`)
- [ ] Tests are independent (order doesn't matter)
- [ ] Tests are deterministic (no `Date.now()`, no `random()`)
- [ ] Edge cases are covered (empty, single, max, invalid)
- [ ] A failing test names the problem specifically

### If Performance (see `domains/performance/`)
- [ ] No unbounded operations (loops, allocations, queries)
- [ ] No N+1 queries
- [ ] Every external call has a timeout
- [ ] Caches have invalidation strategies

### If Observability (see `domains/observability/`)
- [ ] Logs are structured (JSON, fields)
- [ ] Every request has a correlation ID
- [ ] No high-cardinality labels in metrics
- [ ] Alerts have runbooks

### If Errors (see `domains/errors/`)
- [ ] Errors are not swallowed silently
- [ ] Errors are specific (not generic "something went wrong")
- [ ] Errors preserve context (where, when, why, what)
- [ ] Recovery is attempted when possible; fail fast when not

### If Concurrency (see `domains/concurrency/`)
- [ ] Shared state is minimized; immutability preferred
- [ ] Locks are minimal in scope
- [ ] Queues are bounded
- [ ] Every blocking call has a timeout
- [ ] Cancellation is supported

### If DevOps (see `domains/devops/`)
- [ ] The pipeline is the process (no manual steps)
- [ ] Rollback path is known
- [ ] Config is in code, not on the server
- [ ] Environments are parity (dev = prod modulo data)

### If Infrastructure as Code (see `domains/infrastructure-as-code/`)
- [ ] Configuration is declarative, not scripted (P1)
- [ ] Provider versions are pinned, never `latest` (P5)
- [ ] State is remote with locking; never committed (P3, P8)
- [ ] `plan` is reviewed before every `apply` (P4)
- [ ] No secrets in HCL; secrets via providers/stores (P10)
- [ ] Modules are versioned; copy-paste replaced by module calls (P6)
- [ ] Drift is treated as an incident, not a shortcut (P9)
- [ ] Provider credentials scoped per environment, least privilege (P7)

### If Kubernetes (see `domains/kubernetes/`)
- [ ] No bare pods; controllers used (P2)
- [ ] Resource requests set on every prod container (P4)
- [ ] Liveness/readiness/startup probes defined (P5)
- [ ] RBAC bound to ServiceAccounts by intent; no `cluster-admin` (P7)
- [ ] No `:latest` image tag in prod (P5 Version Everything)
- [ ] StatefulSet PVCs use `volumeClaimTemplates`; `emptyDir` only for scratch (P8)
- [ ] ConfigMaps and Secrets separate; secrets not in image (P9)
- [ ] Default-deny NetworkPolicy baseline (P6)
- [ ] Rollout history retained; rollback tested (P10)
- [ ] Namespaces used to bound blast radius; not `default` in prod (P6)

### If GitOps + Operators (see `domains/gitops-operators/`)
- [ ] Desired state lives in git, not in the cluster (P1)
- [ ] Configuration is declarative, not imperative scripts (P2)
- [ ] Reconciliation is pull-based; no external push credentials into the cluster (P3)
- [ ] Reconciliation loop runs continuously; drift auto-corrected (P4)
- [ ] Every change is a commit; history is the audit/rollback path (P5)
- [ ] Operational knowledge encoded as CRDs/controllers, not runbooks (P6)
- [ ] Progressive delivery (canary/blue-green) has a tested abort/rollback path (P7)
- [ ] No manual `kubectl apply`/`kubectl edit` on GitOps-managed resources (P8)
- [ ] Sync failures, health degradation, and rollout stalls emit status + notifications (P9)
- [ ] Controller credentials scoped to reconciled namespaces/resources; no cluster-admin GitOps robot (P10)

### If AI / ML (see `domains/ai-ml/`)
- [ ] Scope check: this is engineering discipline (data versioning, evaluation, serving, drift), NOT algorithm/model design (D-023) — reject algorithm-design content
- [ ] Every training run is reproducible from pinned data + code + config + environment (P1)
- [ ] Datasets, features, and splits are versioned artifacts with lineage; `git` alone is insufficient (P2)
- [ ] Any deployed prediction traces back through model → training run → dataset → source (P3)
- [ ] Metrics, splits, and thresholds declared a priori; no post-hoc metric cherry-picking (P4)
- [ ] Models are pinned, immutable, registry-tracked artifacts; never "the latest" (P5)
- [ ] Inference latency, throughput, input distributions, and prediction confidence are observed (P6)
- [ ] Data drift, concept drift, and prediction drift are monitored; a drift signal is an incident (P7)
- [ ] Inference inputs validated against the model's contract (schema, ranges, types); out-of-contract rejected (P8)
- [ ] Training/serving flows are composable pipelines with explicit steps; notebooks not in production (P9)
- [ ] Serving rollback restores the prior model artifact, not just the prior code (P10)

### If i18n (see `domains/i18n/`)
- [ ] Source language treated as one locale among many, not the "neutral" default (P1)
- [ ] Locale identifiers use BCP 47 tags; no ad-hoc locale codes (P2)
- [ ] User-facing strings in locale resource files, not concatenated inline in code (P3)
- [ ] Plural/gender/select use ICU MessageFormat (or equivalent); no `if (n == 1)` branching (P4)
- [ ] Dates, times, numbers, currencies, units via ICU/CLDR/`Intl`; no hand-rolled formatters (P5)
- [ ] RTL/bidi is a first-class layout concern; logical CSS properties (`start`/`end`) over physical (`left`/`right`) (P6)
- [ ] Layouts accommodate translation expansion; no fixed pixel widths for text (P7)
- [ ] Pseudo-locales (accented, lengthened, RTL-mirrored) used to test before real translations arrive (P8)
- [ ] Icons, colors, and imagery reviewed for locale-sensitivity; no locale-bound symbols treated as universal (P9)
- [ ] Resource files versioned; a bad translation is a rollback, not a hot-patch (P10)

### If Compliance (see `domains/compliance/`)
- [ ] Scope check: framework-agnostic — no regulation-specific (GDPR/HIPAA/SOC2/PCI) content (D-024)
- [ ] Audit records are immutable once written; deletion/mutation is itself an auditable incident (P1)
- [ ] The set of auditable actions is defined a priori; "we forgot to log it" is a violation (P2)
- [ ] Data lifetime is declared and enforced as policy; deletion at end-of-life is a feature (P3)
- [ ] Compliance policy expressed in versioned, reviewable, testable code (OPA/Cedar/Kyverno/Sentinel), not spreadsheets/prose (P4)
- [ ] Policy violations block before the action (admission/CI/CD-time), not after the audit (P5)
- [ ] Evidence gathered as a byproduct of operation, not assembled manually at audit time (P6)
- [ ] Every logged action traces to an authenticated principal; no shared/generic identities (P7)
- [ ] Data-subject rights (access, export, deletion) are operations with defined contracts and audit trails (P8)
- [ ] Audit logs do not leak secrets; redaction is structural, not opportunistic (P9)
- [ ] System reports its own compliance state (drift from policy, open violations, retention status) (P10)

## Final Gate

- [ ] Have I read the relevant domain's first-principles?
- [ ] Have I run the domain-specific checklist?
- [ ] Have I run the core checklist?
- [ ] Are all failures either fixed or explicitly justified in the task notes?

If any unchecked item is not justified, the task is not complete. Do not mark done.