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)

If Edge (see domains/edge/)

• Compute is placed near the user/data source; latency is treated as a correctness constraint, not a perf preference (P1)
• The system continues to operate offline; partition is the norm, not the exception; reconciliation happens on reconnect (P2)
• Edge-node resource constraints (CPU/memory/power/bandwidth) are declared per node class, not assumed infinite (P3)
• Sync conflicts converge; no oscillation or infinite sync loops (P4)
• Sync, cache-fill, and device commands are idempotent — retries are safe (P5)
• Edge caches have an explicit TTL or invalidation strategy; no TTL-less caches under partition (P6)
• Partial degradation is a designed state with a defined contract, not a crash (P7)
• Routing, fan-out, and data placement are location-aware decisions, not accidents of deployment (P8)
• Edge-device credentials are scoped and per-device; no edge node is a cluster-admin-equivalent (P9)
• Telemetry is local-first: buffered on-node and forwarded on reconnect; partition does not blind the operator (P10)

If Messaging (see domains/messaging/)

• Messages have an explicit, versioned schema; producer and consumer agree on shape before exchange (P1)
• Ordering guarantees (per-partition, global, none) are explicit and documented; "FIFO" is backed by the broker contract (P2)
• Consumers are idempotent — redelivery is deduped via idempotency keys or deterministic processing (P3)
• Delivery semantics (at-least-once/at-most-once/exactly-once) are a declared choice per channel (P4)
• Poison messages route to a dead-letter queue; the DLQ is observable and drainable (P5)
• Backpressure is bounded — consumer lag visible, max-unacked bounded, retry budget capped (P6)
• Partition key choice is a documented design decision (ordering vs parallelism vs hotspots) (P7)
• Retention windows and replay-from-offset are explicit; the broker is a durable log, not a pipe (P8)
• Schema changes are backward/forward-compatible; breaking changes are versioned migrations, not silent shape edits (P9)
• Consumer lag, DLQ depth, throughput, and consumer-group health are observed; silent backlog is a bug (P10)

If Language-Derived Docs (see languages/)

• Scope check: no new P-rules introduced — every section traces to an existing domain P-rule (D-063, D-066)
• Every section header names ≥1 traced domain P-rule AND the core C-rule(s) inline (e.g., ## Nominal vs Structural Typing (C1 Correctness, Data P7 Type Fidelity, API P1 Contract Fidelity))
• Fenced code examples are in-language and illustrative only — no standalone .ts/.py/.go/.rs runtime artifacts (D-020)
• The first-principles stub retains its section structure — no P1–P10 numbering added to languages (D-063)
• Cross-links to traced domain docs are present (≥1 outbound per derived doc, ATELIER-114)

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.