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)

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.