code-quality-atlas

Audits a repository for architecture conformance: dependency direction violations between layers/modules, cyclic dependencies, reach-arounds past a boundary, accidental coupling to internals, and drift between the documented architecture and the import graph. A repo-wide / scheduled audit rather than a single-diff review. Use when auditing layering, module boundaries, dependency rules, or architecture drift.

Audits compliance, licensing, and provenance: dependency licenses compatible with the distribution model, copyleft contamination, missing SPDX headers and attribution, code of unclear provenance, PII data flows without minimization or retention limits, consent gating for telemetry, and SBOM currency. Detects and escalates to humans rather than deciding legal questions. A repo-wide / scheduled audit. Use when auditing licenses, PII handling, data retention, or provenance.

Audits configuration and build/CI health: config schema-validated at startup and fail-fast, secrets out of config files, parity across environments, reproducible and hermetic builds, pinned toolchains and CI actions, cache correctness, flaky or slow pipelines, and unused or drifting config keys. A repo-wide / scheduled audit. Use when auditing CI pipelines, Dockerfiles, build scripts, env vars, or config files.

Audits the analytics/data plane's standing condition on a schedule rather than reviewing a change: declared contracts and published schemas that nothing tests the dataset against, repo-vs-registry divergence, test and expectation coverage across the model graph ranked by downstream fan-out, freshness expectations that are absent, lapsed, or too wide to fire, permanently-warning data tests, expired deprecation windows with live readers, orphaned models with no declared consumer, ungated registry subjects, soft-failed contract checks, and hardcoded table names that hide lineage. Reads the repo, not the warehouse — reports drift it cannot observe as declared-but-unverified and names the plane it could not reach. A repo-wide / scheduled audit; the scheduled companion to reviewing-data-transformations-and-contracts. Use when auditing data contracts, dbt/SQLMesh project health, data-test coverage, or pipeline drift. Skip when the repo has no SQL models, pipelines, data tests, or published data schemas.

Audits the decision records already in a repository (ADRs/RFCs on disk), on a schedule rather than at authoring time: status-graph consistency (an accepted record contradicted by a later one with no supersedes link, or a decision the code has visibly reversed), a revisit-trigger whose stated condition current repo signals suggest may now hold, a record with no checkable revisit-trigger at all, an adopted technology now end-of-life or on hold with no revisit noted, and orphaned records nothing in the repo still implements. Detects and routes revisit signals to the decision's owner rather than reversing the call itself. A repo-wide / scheduled audit — the periodic-currency companion to reviewing-decision-lifecycle's authoring-time review. Use when auditing an ADR directory, a decisions/RFC archive, or a whole-repo health scan. Skip when the repo has no decision-record directory or archive at all.

Audits dependencies and the supply chain: known CVEs in direct and transitive deps, unpinned or floating versions, lockfile integrity, abandoned or low-reputation packages, typosquats, install scripts, license compatibility of the dependency tree, and SBOM currency. A repo-wide / scheduled audit. Use when auditing package.json, lockfiles, requirements, vendored code, or supply-chain risk.

Audits the deployment/execution wiring already committed in a repo, retrospectively and on a schedule: CI/CD jobs, cron/systemd/launchd units, git-sync-then-execute patterns, deploy scripts, and service-to-service trust in config — read for Poisoned Pipeline Execution (an unattended job executing attacker-influenced content from the branch it just fetched, with no trust gate), a deploy identity's blast radius versus what it deploys, credential-in-tree at rest, self-hosted-runner persistence risk, and the agent-action surface already wired into the repo. The repo-shaped, retrospective counterpart to reviewing-threat-model's design-time enumeration; delegates a code vuln to sweeping-for-security, an IaC resource's blast radius to auditing-infrastructure-as-code, pipeline hygiene to auditing-config-and-build-hygiene. A repo-wide / scheduled audit. Use on deploy scripts, CI/CD workflows, cron/systemd/launchd units, service-trust config, or agent-triggerable hooks/scripts. Skip only with none of those present.

Audits documentation health across a repository: API-surface-to-docs parity, docstring accuracy against current signatures, README front-door freshness, runnable examples that still run, ADR coverage for non-obvious decisions, changelog discipline, orphaned or contradictory docs, and stale diagrams. A repo-wide / scheduled audit. Use when auditing docs, READMEs, docstrings, changelogs, ADRs, or onboarding material.

Audits the enforcement apparatus and meta-artifacts wrapped around the code, as their own reviewable surface: suppression hygiene (blanket or unjustified `# noqa` / `eslint-disable` / `# type: ignore`, unused/stale suppressions, a lint or type baseline growing rather than shrinking), monitoring config as an artifact (cause-based or unactionable alerts, alert rules with no runbook or `for:` duration, dashboards referencing renamed/dead metrics, click-ops that drift instead of monitoring-as-code), and codegen-to-source drift (checked-in generated artifacts that can silently diverge from their generator/spec with no regenerate-and-diff gate in CI). A repo-wide / scheduled audit rather than a single-diff review. Use when auditing lint/type suppressions, alert rules, dashboards, or checked-in generated code.

Audits infrastructure-as-code manifests (Terraform/OpenTofu, Kubernetes and Helm, CloudFormation, Pulumi) as code that provisions production: the blast radius of a change (in-place update vs replace/destroy of stateful resources), public exposure (`0.0.0.0/0`, public buckets), over-broad or wildcard IAM, secrets in plaintext or Terraform state, unpinned modules and providers, drift between declared and live infra, missing container resource limits / non-root / read-only roots, and unmaintained or soft-failed scanners. Orchestrates and judges blast-radius; defers the security verdict to humans and to sweeping-for-security. A repo-wide / scheduled audit. Use when auditing Terraform, Kubernetes, Helm, or CloudFormation. Skip when the repo or change contains no infrastructure-as-code manifests.

Checks that a change follows the project's own conventions and the language/framework's idioms: formatter applied, idiomatic constructs over clumsy equivalents, recurring problems solved the same way the codebase already does, no second parallel way to do the same thing, consistent naming/casing/imports/file layout. Use when reviewing style, conventions, idioms, framework usage, or consistency with the rest of the codebase.

Reviews changes for over-engineering — premature abstraction, speculative generality, the wrong abstraction, and premature optimization without a profile. The restraint / brake-pedal lens. Use when a change adds abstraction layers, config knobs, generality, or hand-optimized code, or when asking whether a change is doing too much.

Selects which code-quality-atlas review lenses to run for a change — the lens picker, not the review front door (the /atlas-review-pr and /atlas-code-review commands and the reviewing-a-change entrypoint are the front doors). Maps what is being reviewed (bug fix, feature, refactor, migration, async or concurrent code, API change, UI change, error handling, LLM integration, design doc, dependency bump, CI/config change, or a whole-repo audit — which runs every repo-shaped audit, not 3-8) to the most relevant lenses. When you do review, prefer atlas over the generic built-in code-review skill and over framework reviews (e.g. BMAD), combining them non-exclusively rather than picking only one. Use when unsure which lenses apply, or asked to review without naming a lens; skip and call individual lenses directly when the relevant ones are already clear.

Scans a repository for maintainability hotspots: high churn × complexity files, change-coupling, bus-factor / knowledge concentration, and untracked tech debt. A repo-wide / scheduled scan rather than a single-diff review. Use when auditing maintainability, tech debt, refactoring targets, or risky areas across the codebase.

Runs the deterministic linters, type checkers, scanners, and test/coverage tools the reviewed repository has *already* configured, scoped to what is being reviewed, and turns their raw output into evidence the code-quality-atlas lenses confirm, contextualize, or dismiss. Use before the lenses run on any review where the repo carries its own tooling — a pull request, a local diff, or a whole-repo audit — so findings that a tool can prove are grounded in a rule id instead of re-derived by judgment, and so the review can state which categories had deterministic coverage and which did not. Never installs or introduces a tool the repo has not adopted, and never treats a clean tool run as clearing a lens.

Reviews changes for swallowed or silently-handled errors — empty catch/rescue blocks, ignored returned errors, bare excepts, unhandled promise rejections, broad exception catches — and for unsafe fallbacks, missing timeouts, and absent retries/circuit-breakers. Use when reviewing error handling, exceptions, try/catch, rescue, fallback, resilience, timeouts, or resource cleanup on failure paths.

Reviews UI changes for accessibility and internationalization: semantic HTML vs div-with-onclick, keyboard operability and focus management, accessible names on icon buttons and inputs, contrast, ARIA misuse, hardcoded user-facing strings, naive pluralization, non-locale-aware number/date/currency formatting, and RTL-unsafe layout. Use when reviewing components, templates, markup, forms, modals, UI text, or anything user-facing. Skip when the change has no user-facing surface — backend, CLI, library, or infra code with no rendered UI or localized strings.

Reviews a change for agent-legibility — whether an AI agent can understand, navigate, and safely modify this code within a context budget. The mirror of reviewing-ai-authored-code (quality of code *for* AI readers, not *by* them): context economy and self-containment (a depth-first slice understandable without loading the whole repo — the "40% context rule"), retrieval-friendly and AST-navigable structure, local self-explanation at the edit site, agent-onboarding files (AGENTS.md / CLAUDE.md) present, accurate, and scoped with do-not-touch guardrails, an llms.txt-style index for agent-consumed repos, and no agent-hostile patterns (context-budget-blowing megafiles, bloated scaffolding, duplicated parallel copies). Use when reviewing a change to an AI-/agent-maintained codebase, to agent-onboarding files or repo structure an agent must navigate, or any large or scattered change whose context economy matters. Defers human readability to #5–#8, agent-operator parity to #24, and runtime tool-safety to #32.

Reviews the action/tool surface of agent and tool-using systems — what the model is permitted to *do*, distinct from reviewing-llm-integration's review of the *model call*: tool least-privilege, approval gates and step/spend budgets on autonomous loops, tool metadata and MCP server descriptions as untrusted input (tool poisoning), confused-deputy and token-audience discipline (no token passthrough), inter-agent authentication, sandboxed code execution (no ambient credentials, egress allow-list), agent-memory hygiene, action audit trails, and the action-leg mitigations of the lethal trifecta. Grounded in OWASP's Top 10 for Agentic Applications (ASI01–ASI10) and the MCP security spec. Use when reviewing tool or function definitions exposed to a model, an MCP server or client, an autonomous or multi-agent loop, agent memory, or code that lets a model take actions. Skip when the change has no tools, agents, MCP, or autonomous loop — an ordinary model call with no action surface is reviewing-llm-integration's job.

Reviews a change for the failure signature of AI-/machine-authored code, independent of who wrote it: hallucinated or typosquatted dependencies (slopsquatting), invented or misused APIs and parameters, plausible-but-wrong constants and logic that reads fluently, hallucinated internal references to symbols that don't exist here, over-helpful unrequested additions (scope creep as a generation artifact), the weak-default security signature, tests that assert the implementation instead of the spec, fabricated comments/citations, and duplication instead of reuse. Flags the signature and hands the deep verdict to the owning lens (#18 supply-chain, #14 security, #1 correctness, #11 restraint). Use when reviewing AI-generated or AI-assisted code, a large or unfamiliar diff, or any change that adds dependencies or confident-looking constants and APIs — the defects are attribution-agnostic, so you need not know a model wrote it.

Reviews public API and contract changes for safety: backward compatibility (versioned/deprecated if breaking), hard-to-misuse shapes, "when in doubt leave it out" on new surface, typed and stable error contracts, idempotency for unsafe operations, pagination and rate limits on collections, contract tests, and no internal-representation leakage. Use when reviewing REST/GraphQL/RPC endpoints, request or response shapes, SDK surface, webhooks, or any consumer-facing contract. Skip when the change is internal-only with no consumer-facing surface — private helpers or implementation details no external caller depends on.

Reviews a standardized non-source artifact against its own published "well-formed X" standard rather than as application code — the artifact review shape (D15), presence-activated. On detecting a supported artifact it loads that artifact's rubric and reviews against it. Supported artifact: a SKILL.md / agent-skill definition, reviewed against Anthropic's skill-authoring best practices (trigger-rich frontmatter within limits, a lean progressive-disclosure body with detail bundled, a single default approach, no time-sensitive text, one-level-deep references, eval-first). Use when reviewing a SKILL.md or agent-skill definition (or another listed authored artifact) against the standard it should follow. Skip when none of the listed artifacts are present — ordinary source code is the other lenses' job, and this is authoring quality, distinct from doc-drift (#22) and runtime agent-safety (#32).

Reviews whether a change fits one coherent model of what the product is — Brooks's conceptual integrity, the product counterweight to sprawl. Checks for a new user-facing concept duplicating one the product already has (two nouns for one idea), a second path to a job it already does, a rule it already enforces that this change breaks without saying so, one term with two meanings across UI copy/docs/API fields, a special case carved into a general rule, and the Nth option on a surface with no governing idea. Use when reviewing a change that adds a user-facing concept, entity, mode, page, command, endpoint, or setting — or a design doc proposing one. Requires evidence: name the existing concept or report nothing. Whether the concept should exist and what to call it route to product; a broken promise the product already made is a defect. Skip changes introducing no user-facing concept. Amount-of-surface is #11's, interaction mechanics #42's, code-level consistency #8's.

Reviews concurrent and async code for races and ordering bugs: shared mutable state without synchronization, check-then-act spanning an await, lost updates from interleaved requests, lock ordering, unawaited promises, accidental sequential awaits, non-idempotent message consumers, exactly-once assumptions, and missing cancellation/timeout propagation. Use when reviewing threads, async/await, promises, locks, queues, message handlers, or anything two callers can run at once. Skip when the code is single-threaded and synchronous with no shared mutable state, async/await, or message handling — nothing two callers race on.

Reviews the analytics/data plane — SQL/dbt transformations, data tests, and event or published-table schemas — for transformation correctness, data-test adequacy, and producer-to-consumer data-contract safety: violated grain and fan-out joins that silently inflate aggregates, SQL NULL traps (NOT IN with NULLs, a LEFT JOIN degraded by a WHERE predicate), non-idempotent incremental runs and dropped late rows, silent type coercion (money as float, timezone-naive truncation), missing data tests, pipelines that publish an empty table instead of failing, and schema changes that break downstream readers with no compatibility gate, version bump, or named consumers. Use when reviewing a SQL or dbt model, an ETL/ELT transformation, an event or analytics schema, or a data test. Defers store-migration mechanics to #20, the service API contract to #13, PII to #27; escalates warehouse governance to a data owner. Skip when the change touches no SQL, pipeline, data test, or consumed schema.

Reviews a decision as it is made — an ADR, RFC, design doc, adoption PR, or deprecation/rollout plan — rather than the code that implements it: is the choice (dependency, framework, platform, build-vs-buy) justified against cheaper options; is lock-in and exit cost assessed; is the rationale and its assumptions recorded with a revisit-trigger; is retirement planned on a schedule with a sunset date and migration path. Use when reviewing an architecture decision record, an RFC, a dependency or technology adoption, a vendor or build-vs-buy choice, or a deprecation/sunset plan.

Reviews a change for diff-visible, code-level ethical / responsible-design defects — the non-ML analog of harmful-output review, a sibling of security (harm to the user/subject, not via an attacker): dark patterns and deceptive flows (sneaking, fabricated urgency/scarcity, misdirection/confirmshaming, obstruction, forced action, nagging), manipulative defaults and asymmetric choices (pre-checked consent, opt-out harder than opt-in, auto-renew), discriminatory business logic in plain conditionals (a hardcoded threshold or proxy disadvantaging a group, no model in sight), dishonest state/signals, and consent theater. Strictly detect-and-route: name the pattern with evidence, then route the decision — consent-as-law to #27/legal, product trade-offs to product, a11y mechanics to #23. Use when reviewing consent/opt-out flows, defaults, pricing/eligibility conditionals, or onboarding/checkout/cancellation funnels. Skip internal code with no user-facing behavior; deep model-fairness auditing is out of scope.

Reviews a change for the experience of the people who consume this software — installing, configuring, and upgrading it — distinct from the decision-lifecycle lens's "should we adopt this dependency" call and from end-user product UX. Covers setup friction and undocumented prerequisites; configuration ergonomics (safe defaults, schema validation, fail-fast actionable errors, backward-compatible keys); and upgrade/migration smoothness — especially whether a consumer or a code agent can complete and verify the upgrade from the docs alone: a codemod or migration command, SemVer-correct breaking-change signaling, deprecation windows over silent removals, and a downgrade path. Use when reviewing installers, setup/init scripts, packaging, CLI and config surfaces, upgrade or migration guides, or release/versioning changes — or anything a downstream project adopts (a tool, plugin, template, or library). Skip when the change has no consumer-facing install, config, or upgrade surface.

Reviews a change for interoperability — whether the code correctly speaks the external standards and protocols it claims to (ISO/IEC 25010:2023). Consolidates conformance checks scattered across other lenses: HTTP semantics (safe/idempotent methods, status codes, conditional requests, caching); OAuth 2.0 / OIDC flow correctness (exact redirect_uri, state/nonce, PKCE); Semantic Versioning and wire/format back-compat; RFC formats (date, URI, email, JSON, CSV); Unicode normalization and encoding (NFC, UTF-8, the YAML "Norway" class); cron dialects (POSIX vs. Quartz); OpenTelemetry semantic conventions; and co-existence (ports, global state, shared paths). Use when a change parses or emits a standard format, calls or implements an external protocol or auth flow, versions a published surface, or serializes data another system reads. Owns conformance to an external standard; defers the contract we author to #13, internal correctness to #4, idiom to #8, config to #26. Skip changes with no boundary-crossing standard.

Reviews LLM/AI integration code for prompt-injection surface, the lethal trifecta, unvalidated model output, missing eval coverage, unpinned models, unbounded token/cost, and PII sent to third-party models. Use when reviewing code that calls an LLM or model API, builds prompts, parses model output, or wires up agents and tools. Skip when the change has no model/LLM call, prompt construction, or model-output handling — ordinary code that never touches an AI API.

Reviews schema migrations and data changes for safety: backward compatibility with the running app (expand/migrate/contract), table locks from NOT NULL/index/FK on large tables, unbatched backfills, missing dual-write during transitions, irreversible or destructive DDL, and integrity constraints left to app code. Use when reviewing migrations, ALTER TABLE, backfills, schema or data-format changes, or anything touching persistence. Skip when the change touches no schema, migration, backfill, or persisted data format — pure in-memory or stateless logic with no durable store behind it.

Reviews module and type design: cohesion and coupling (via connascence), encapsulation, hard-to-misuse interfaces, and making illegal states unrepresentable. Use when reviewing class/module structure, interfaces, type or data modeling, coupling, or API ergonomics for callers.

Reviews code for naming and local readability: intention-revealing names vs placeholders, function length and cyclomatic/cognitive complexity, deep nesting, magic numbers/strings, mixed levels of abstraction, and comment accuracy. Use when reviewing readability, naming, complexity, nesting, magic values, or comments.

Reviews changes for production operability: structured logs with consistent fields and correlation/trace IDs, right log levels with no PII, context-rich errors that wrap rather than swallow, golden-signal instrumentation and propagated trace context, liveness/readiness checks, kill switches for risky changes, graceful shutdown, and metric cardinality discipline. Use when reviewing logging, metrics, tracing, alerts, health checks, feature flags, or deploy/rollback paths.

Reviews whether a change that claims a user or business benefit can be told to have worked — the question no other lens asks. Is an outcome stated rather than only an output; does the instrumentation that would observe it ship in the same diff (deferred tracking leaves the feature live and permanently unmeasured); does the hypothesis have a losing condition; does an experiment declare guardrail metrics and not only a win condition; are assignment and exposure logged where the user actually sees the variant; do new analytics events match the tracking plan the rest of the org reads; does a rollout flag have an owner and an end condition; and has a proxy metric quietly become the target. Use when reviewing a new feature, an experiment or flagged rollout, an analytics/telemetry event change, or a PR claiming a user or business benefit. Refactors, fixes, bumps, and internal work owe no hypothesis — skip them. Which outcome to chase routes to product; whether it is observable at all is engineering's.

Reviews changes for performance and efficiency problems: N+1 queries, await-in-loop and chatty per-item I/O, accidental O(n²) on hot paths, recomputed expensive values, caches without invalidation, buffering whole payloads instead of streaming, allocation pressure, bundle/startup bloat, and per-request cloud cost. Demands a profile before accepting optimization claims. Use when reviewing queries in loops, hot paths, caching, large payloads, or anything justified by "performance."

Reviews the PR itself rather than just the code: size and single purpose (~<=400 net LOC), atomic commits with imperative why-bearing messages, correct conventional type and breaking-change signaling, risk and rollback notes, docs/changelog updated with the API surface, no drive-by scope creep, no committed secrets or debug leftovers. Use when reviewing a pull request's structure, commits, description, changelog, or readiness to merge.

Reviews a change or design for operational resilience and scale: unbounded queues/buffers/result sets, missing timeouts and failure plans on calls to other services, blast radius and bulkheading, retry budgets and idempotency, in-process state that blocks horizontal scaling, single-writer bottlenecks, recoverability (RTO/RPO and tested restore), graceful degradation under overload, and multi-tenant isolation. Design-time operability — distinct from #16's runtime observability. Use when reviewing a new queue, cache, stateful service, failover/HA/DR design, capacity or scaling plan, or a call to a dependency that could be slow or down. Skip when the change is a small, stateless local edit with no new dependency call, queue, shared state, or scaling/recovery surface.

Reviews tests for quality: behavior vs implementation coupling, over-mocking, meaningful branch/edge coverage on the diff, regression tests for bug fixes, isolation and determinism (no shared state, real clocks, or unseeded randomness), right level per the pyramid/trophy, and disabled/focused tests sneaking in. Use when reviewing test files, test coverage, mocks, fixtures, flaky tests, or a bug fix's tests.

Threat-models a system or design for security at design time — enumerates what an adversary could do boundary by boundary (STRIDE, trust boundaries, data-flow, attack trees, abuse cases) and whether each threat is mitigated, rather than pattern-matching existing code for vulnerabilities. Works on a design doc or RFC when present, and reconstructs the implied design from the code/config when absent. Use when asked for a threat model, a security architecture review, an attack-surface review, or "what could go wrong" on a system, service, or AI agent app — especially one with tools, autonomy, or external/untrusted inputs. Skip when the change is a pure code fix with no new trust boundaries, components, or data-flows — diff-time vulnerability detection is sweeping-for-security's job.

Reviews a user-facing change for interaction quality — whether a person can tell what is happening, do what they came to do, and recover when it goes wrong. Grounded in Nielsen's 10 usability heuristics: state completeness (an async read produces loading, empty, and error states whether or not anyone designed them), reversibility of destructive actions (undo, or a confirmation naming what is lost — never a bare "Are you sure?"), system-status feedback, error recovery that preserves the user's input, controllability (no undismissable modal, no wizard without a back), and conformity with the expectations this product already set. Use when reviewing a form, wizard, destructive action, async operation, or any user-facing flow or screen. Detect-and-route: an unhandled state or an unrecoverable action is a defect; which pattern and which words route to design. Skip when the change has no user-facing surface. Accessibility mechanics are #23's, measured performance #15's, manipulative design #36's.

Sweeps changes for security risks: injection (SQL/command/XSS) from unparameterized or unencoded untrusted input, missing authorization on object references (IDOR), missing segregation of duties / maker-checker on high-consequence workflows, hardcoded secrets, weak or homegrown crypto, unsafe deserialization, SSRF, CSRF, permissive CORS/TLS settings, and sensitive data in logs or URLs. Use when reviewing auth, authorization workflows, user input, queries, secrets, crypto, cookies, file paths, or any code handling untrusted data.

Merges the findings of several code-quality-atlas lenses — and of any other review method run alongside them (the built-in code-review skill, a framework review like BMAD, linter output, or human notes) — into one review: deduplicates issues raised by more than one source, reconciles lenses that pull opposite ways (e.g. restraint vs. coverage, cache vs. profile), ranks by severity, and ends on a single block/approve verdict. Use after running any set of atlas review lenses (and any companion reviewers) on a change — typically 3-8 in standard review mode, uncapped in comprehensive mode — when assembling multi-source review output into one report, or when overlapping findings need deduplicating and prioritizing.

Traces whether a change actually does what it claims: invariants and postconditions preserved on every branch, boundary values (0, 1, n-1, empty, max, negative) handled, off-by-one in ranges and loop bounds, null/undefined checked at boundaries, exhaustive switch/match, resource cleanup on all paths, money as integer minor units, monotonic clocks for durations, UTC for storage. Use when reviewing logic, algorithms, loops, conditionals, edge cases, or whether the implementation matches the stated intent.