Jon Chery
d1aa5daf2b
---ci--- project: atelier phase: 5 milestone: v0.2 status: complete requirements: covered: [ATELIER-36, ATELIER-37, ATELIER-38, ATELIER-39, ATELIER-40, ATELIER-41, ATELIER-42, ATELIER-43, ATELIER-44, ATELIER-45, ATELIER-46, ATELIER-47, ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56, ATELIER-57, ATELIER-58, ATELIER-59] partial: [] ---/ci---
157 lines
6.4 KiB
Markdown
157 lines
6.4 KiB
Markdown
# 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)
|
||
|
||
## 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. |