Concerns

Every card's rule on one page, and each row links to the full card. Pick one or more concerns to scope a review, such as performance only. A card matches when it lists any picked concern. Report each check as PASS, FAIL, or N/A with file:line evidence. A FAIL carries the card's severity. Any block FAIL means request changes. A should-fix or discuss FAIL goes in the review but does not block.

FAIL [block] chg-expand-contract - src/a.py:42 - renames the column and drops the old one in one migration
FAIL [should-fix] chg-one-concern - src/b.py:7 - a logging rewrite rides along with the bug fix
PASS chg-breaking-change-taxonomy - src/c.py:15 - no signature or return shape changes
N/A chg-perf-claim-evidence - the description makes no performance claim

Checklist

What the badges mean

Filters

Concerns
Levels
Topic tags
Topics

Draft cards

136 draft cards

A draft card is not vetted. Read it for ideas, but do not use it for a verdict. Each row links to the full card.

  • code-a11y-check-in-ci should-fixaccessibilitytestingRun an automated accessibility check, such as axe on rendered pages, in the automated tests, and fail the test on a violation.
  • code-ai-pr-disclosure should-fixprocessDisclose AI assistance in the PR, and have a human author who can explain and defend every changed line without the tool.
  • code-documented-setup-runs should-fixmaintainabilityprocessMake every setup, build and run command in the README or contribution guide succeed on a clean checkout.
  • code-file-lines-ceiling discussmaintainabilityprocessKeep every hand-written source file under about 1,000 lines unless it has a listed exception, and split larger files by knowledge owned, not by execution order.
  • code-flaky-test-quarantine should-fixtestingprocessReport every test that passes only on retry, move it to a quarantine with a named owner and a ticket, and return it to the merge gate only after it passes many reruns.
  • code-scoped-validation-loop discusstestingprocessDocument a command that checks one package or path, with readable output, so a small change does not need the full-repo run.
  • fn-atomic-related-updates blockcorrectnessMake related writes succeed or fail together: one transaction, or an ordered sequence with a defined undo.
  • fn-bool-arg-at-callsite discussmaintainabilityReplace a boolean flag argument with an enum, keyword-only argument or two functions.
  • fn-comments-survive-context should-fixmaintainabilityWrite comments that remain true without outside context: no "see the PR", "currently", "not yet", ticket ids or codenames.
  • fn-distinct-types-for-ids should-fixcorrectnessGive arguments with different meanings distinct types, so a call that swaps them fails to type-check.
  • fn-empty-collection-not-none should-fixcorrectnessReturn an empty collection for "nothing found"; return None only when absent differs from empty.
  • fn-english-identifiers discussmaintainabilityWrite identifiers and comments in English, unless the project policy names another language.
  • fn-known-keys-get-a-type should-fixcorrectnessGive a fixed key set a record type (model, dataclass, or typed dict), and use a generic map only for open keys.
  • fn-name-intermediate-conditions discussmaintainabilityName each compound condition by assigning its sub-conditions to booleans that say what they mean.
  • fn-no-anonymous-tuples should-fixmaintainabilityReturn a small named record, not a positional tuple, once the fields differ in meaning.
  • fn-no-check-then-act-across-await blockcorrectnessMake check-and-write one atomic operation where the state lives, and never split it across a suspension point.
  • fn-no-eval-untrusted blocksecurityNever pass untrusted text to eval, exec, new Function, an expression language, or a template compiler. Pass it to a fixed template or a parser as data.
  • fn-no-getattr-for-known-names discussmaintainabilityUse plain field access, and reserve dynamic access for genuinely dynamic names.
  • fn-no-magic-values should-fixmaintainabilityGive every meaningful literal a name: an enum member or a constant.
  • fn-no-pass-through-wrapper should-fixmaintainabilityDelete a method that only forwards, and keep wrappers that validate, adapt, or narrow.
  • fn-no-prototype-pollution blocksecurityNever write an untrusted key into a plain object. Use a Map, an object from Object.create(null), or an allowlist of keys, and block __proto__, constructor, and prototype in any deep merge.
  • fn-no-stringly-typed-returns should-fixcorrectnesscompatibilityReturn an enum or a tagged type, never a bare string that the caller must compare.
  • fn-propagate-dont-swallow blockcorrectnessChain the original cause when you translate an exception.
  • fn-redirect-target-allowlist should-fixsecurityRedirect only to a local path or to a host on a server-side allowlist, never to a URL taken from the request as is.
  • fn-resource-lifetime blockcorrectnessGive every task and handle an owner that waits for it or closes it, on the error path too.
  • fn-specific-exceptions-only blockcorrectnessCatch only the specific exception you can handle in business code.
  • fn-test-oracle-independent should-fixcorrectnesstestingTake a test's expected value from the requirement, not from the code under test, and pair every "not called" assertion with a case where the call happens.
  • fn-variants-as-tagged-union should-fixmaintainabilityModel variants as a tagged union, and make every switch over it fail the build when a variant is unhandled.
  • fn-xml-no-external-entities blocksecurityParse untrusted XML with DTDs, external entities, and network access turned off, or with a hardened wrapper such as defusedxml.
  • inc-perf-regression-guard should-fixperformancetestingAdd an automated check that would have caught the regression (a benchmark, a budget, a load-test threshold, or a resource guard) as one of the postmortem's actions.
  • inc-postmortem-owned-actions should-fixreliabilityprocessGive every postmortem action one named owner, a due date, and a tracker link.
  • mod-behaviour-lives-with-state discussmaintainabilityPut invariants and calculations over one object on that object, and move logic to a service only when it spans objects or needs an injected collaborator.
  • mod-central-config should-fixmaintainabilityRead configuration in one settings module and pass it in; business code must not read the environment or hold knobs.
  • mod-cohesive-unit discussmaintainabilityKeep one cohesive concept per module.
  • mod-deep-modules discussmaintainabilityPrefer a small interface that hides real work, and flag modules whose interface is nearly as complex as their implementation.
  • mod-fowler-smells discussmaintainabilityName the smell, point to the line, and suggest the refactoring; do not file smells as taste.
  • mod-inject-boundary-collaborators should-fixtestingmaintainabilityInject boundary collaborators through the constructor; do not construct them inside or reach for a global.
  • mod-internals-unreachable should-fixmaintainabilityMake a module's internals unimportable from outside it, and have a check fail the build when a caller reaches in.
  • mod-layers-point-inward should-fixmaintainabilityMake dependencies point inward: surface, then logic, then boundary.
  • mod-mock-at-boundaries-only should-fixtestingMock only at the process boundary (HTTP, DB, cloud, clock, I/O).
  • mod-no-import-side-effects blocktestingmaintainabilityKeep I/O at the edges: importing a package must not touch the network, read files, or read the environment.
  • mod-no-logic-in-constructors should-fixcorrectnesstestingAssign only in constructors, and put I/O, parsing, and heavy computation in a named factory.
  • mod-no-module-mutable-state should-fixcorrectnesstestingKeep no mutable state at module level.
  • mod-no-utils-grab-bag should-fixmaintainabilityPut a helper in the module that owns the concept, or in a new module named after the concept.
  • mod-no-wire-types-in-public-api should-fixmaintainabilityExpose domain types in a module's public interface, and keep transport, storage and framework types behind it.
  • mod-no-wrong-abstraction should-fixmaintainabilityInline an abstraction that has grown flags for its callers, then re-split it.
  • mod-one-name-per-concept should-fixmaintainabilityUse one name for one concept across the codebase.
  • mod-prefer-sync-api discusscorrectnessKeep logic in plain synchronous functions with no I/O, and add async wrappers at the edge only.
  • mod-proto-enum-zero-unspecified should-fixcompatibilityGive every protobuf enum a zero value named <ENUM>_UNSPECIFIED with no real meaning.
  • mod-subtype-passes-parent-tests should-fixmaintainabilityMake a subtype pass its parent's tests: accept every input the parent accepts, promise at least what it promises, and keep its invariants.
  • mod-thin-entry-point should-fixmaintainabilityKeep the entry module to wiring (bootstrap, configuration, lifespan) and put no business logic in it.
  • mod-validate-at-boundary-once should-fixcorrectnessmaintainabilityValidate at the boundary, once, with a schema or model, so that inner layers receive typed, already-valid data.
  • prod-a11y-audit-before-launch should-fixaccessibilityusabilityBefore a public launch, run an accessibility audit against WCAG 2.2 AA that includes assistive technology, and link the report in the launch checklist.
  • prod-shadow-compare-before-cutover should-fixcorrectnessreliabilityBefore you move traffic to a new system, run it beside the old one on live or captured production traffic, diff the results, and cut over only when every mismatch is fixed or explained.
  • prod-slo-error-budget discussreliabilityobservabilityDefine an SLO with an indicator and window, and use its remaining error budget to gate risky releases.
  • prod-wide-events-bounded-labels should-fixobservabilityEmit one structured event per request carrying trace, tenant, build and flag state.
  • svc-api-cache-control should-fixperformanceSet an explicit Cache-Control on every response a cache may store, use private or no-store for user-specific data, and add Vary for any request header that changes the body.
  • svc-api-contract-tests should-fixcompatibilitytestingRun a contract test for each cross-service call, derived from the consumer's real requests, and fail the provider's build when it breaks one.
  • svc-api-documented-errors should-fixcorrectnesscompatibilityDocument every error status each operation can return, with a schema and one example.
  • svc-api-naming-consistent discussmaintainabilityUse one casing convention per location (fields, query parameters, headers, paths) across the whole API, and state it in the API guide.
  • svc-api-problem-json should-fixcompatibilityReturn errors as application/problem+json with a status that equals the HTTP status, and leave stack traces and internal detail out.
  • svc-api-retry-after should-fixreliabilitySend Retry-After on every 429 and 503, and set it no earlier than the time capacity returns.
  • svc-api-safe-idempotent-methods blockcompatibilityKeep GET, HEAD and OPTIONS free of side effects, and make PUT and DELETE give the same end state when repeated.
  • svc-api-spec-matches-impl should-fixcompatibilityKeep the OpenAPI document as the source of truth, and generate it from the code or test the running service against it in CI.
  • svc-api-specific-status-codes should-fixcompatibilityReturn the most specific status code that fits: 201 with Location for a create, 405 with Allow for a wrong method, and a 4xx or 5xx for any failure.
  • svc-api-trace-context should-fixobservabilityForward traceparent and tracestate on every outgoing call, keep the incoming trace id, and set a new parent id for each hop.
  • svc-async-content-reserves-space should-fixusabilityperformanceReserve the space for late-loading content with set dimensions or an aspect ratio, so nothing already on screen moves.
  • svc-authn-by-default blocksecurityRequire authentication on every route by default, and mark each public route by name.
  • svc-best-effort-optional-deps should-fixreliabilityobservabilityGive each call to a non-critical dependency a short budget and a default, so its failure degrades the result instead of failing the critical path, and count every fallback.
  • svc-circuit-breaker-bulkhead should-fixreliabilityGive each critical dependency its own concurrency limit.
  • svc-cli-destructive-dry-run should-fixreliabilitymaintainabilityGive a destructive command a preview flag that changes nothing and a flag that skips the confirmation prompt.
  • svc-cli-non-interactive should-fixmaintainabilityprocessGive every input a flag, use a prompt only as a fallback, and exit at once with an example call when a required flag is missing.
  • svc-csp-strict-script-src should-fixsecuritySend a Content-Security-Policy whose script-src uses a per-response nonce or script hashes, with object-src 'none' and base-uri 'none'.
  • svc-dlq should-fixreliabilityGive every consumer queue a dead-letter queue and a way to replay its messages after the fix.
  • svc-no-secrets-in-url should-fixsecuritySend tokens, keys, passwords, and personal data in a header or the request body, never in the path or query string.
  • svc-page-title-per-route should-fixaccessibilityusabilityGive every page and every client-side view its own <title> that says what it is.
  • svc-rate-limit-by-cost should-fixperformancereliabilityWhen request costs differ by orders of magnitude, charge each request its estimated cost against the quota instead of counting it as one.
  • svc-request-id-logging should-fixobservabilityPut the request or trace id on every log line written during a request.
  • svc-saga-steps blockreliabilitycorrectnessMake steps after the pivot idempotent and retryable, and make every compensation idempotent with a failure path.
  • svc-security-event-logging should-fixsecurityobservabilityLog every failed authentication with the account name and a timestamp.
  • svc-security-headers should-fixsecuritySend Strict-Transport-Security on every HTTPS response.
  • svc-stream-dont-materialise should-fixperformanceProcess large results as a stream with backpressure; do not load them whole into memory.
  • svc-tls-modern-only should-fixsecurityAccept only TLS 1.2 and TLS 1.3 on servers, and set that minimum in the config instead of relying on the default.
  • sys-cache-cold-start should-fixperformancereliabilityCap and coalesce the cache-miss path so an empty cache cannot overwhelm the origin.
  • sys-cells-limit-blast-radius discussreliabilitySplit shared infrastructure into independent cells, each with its own control plane and storage, and route each tenant or request to one cell, so one failure stops only that cell.
  • sys-constraint-not-valid blockcompatibilityAdd the constraint NOT VALID, then run VALIDATE CONSTRAINT in a separate step, and never leave the VALIDATE out.
  • sys-health-liveness-readiness blockreliabilityWire load balancers and restarters to liveness and local checks only, never to shared-dependency checks.
  • sys-index-concurrently blockcompatibilityCreate indexes with CONCURRENTLY, outside a transaction block, and handle a failed build that leaves an INVALID index.
  • sys-leader-two-leaders should-fixreliabilityMake leader work safe if two leaders overlap: make it idempotent, check the lease before acting, and stop when renewal fails.
  • sys-migration-lock-timeout blockcompatibilitySet lock_timeout for the migration session and retry on timeout.
  • chg-agent-grounded-code blockmaintainabilityprocessVerify that every import and external call the agent wrote exists with that signature.
  • chg-agent-independent-review should-fixprocessGet sign-off from a person or a fresh-context reviewer who has the spec but not the author's reasoning; self-review by the writing session does not count.
  • chg-agent-mock-asserting-tests blocktestingprocessWrite tests that fail when the behaviour breaks, and reject tests that mostly assert on mocks, copy the implementation, or were edited to match new output without explanation.
  • chg-api-spec-in-same-change should-fixcompatibilityUpdate the API spec in the same change that alters the routes, fields, status codes or headers it describes.
  • chg-approval-tied-to-patch should-fixprocessTreat an approval or verification verdict as current only if no push since then changed non-test content, and compare patch ids after a rebase.
  • chg-chestertons-fence should-fixmaintainabilityprocessAdd a characterization test before rewriting code you do not understand.
  • chg-delete-legacy-after-migration should-fixcompatibilitymaintainabilityWhen no consumer sits outside the repo, move every caller to the new API and delete the old one, and the tests that pinned its internals, in the same change.
  • chg-devex-breaking-config should-fixcompatibilityprocessWhen a change breaks how developers or operators run the project, ship a migration note with it: old name, new name, and what to do.
  • chg-fix-root-cause-not-symptom blockcorrectnesstestingIn a bug fix, state the cause you saw in evidence, and reject a guard, retry, sleep, longer timeout, swallowed error, cast, skipped or weakened test, or special case for the failing input that the cause does not justify.
  • chg-flag-owner-retirement should-fixreliabilityGive every new flag an owner, a default, and a removal condition or date, and ticket the removal.
  • chg-matches-spec blockprocessTrace every behaviour change in the diff to the stated requirement, and flag missing requirements and any change nobody asked for.
  • chg-migration-add-column-rewrite blockcompatibilityAdd the column nullable or with a constant default, then fill volatile, computed, or identity values in batches.
  • chg-name-attack-surface blocksecurityprocessList any new attack surface in the description.
  • chg-new-api-has-usage should-fixmaintainabilityShip new API with at least one real caller in the same change, and fail speculative interfaces and options that nothing uses.
  • chg-new-query-has-plan should-fixperformanceAttach the query plan for each new or rewritten query on a growing table, taken on production-sized data.
  • chg-no-silenced-diagnostics should-fixcorrectnessmaintainabilityprocessName the rule, the reason, and a ticket on every suppression; a swallowed error, skipped test, or disabled check is a FAIL unless justified.
  • chg-no-special-case-branches should-fixmaintainabilityPut a new case behind its own function or type; do not add a one-off branch to a shared flow.
  • chg-proto-no-field-type-change blockcompatibilityNever change the type of a protobuf field, switch it between repeated and scalar, or rename it while any consumer reads JSON or text format; add a new field instead.
  • chg-proto-reserve-removed-fields blockcompatibilityWhen you delete a protobuf field or enum value, add reserved for its number and name in the same change, and never reuse a number.
  • chg-reuse-before-write should-fixmaintainabilitySearch the repo for an existing helper before adding a new one.
  • chg-review-comment-format discussprocessLabel each review comment with its severity: block, should-fix, or discuss.
  • chg-rollback-path blockreliabilityState in the description how to undo the change.
  • chg-ui-change-screenshots-and-keyboard-pass should-fixaccessibilityusabilityprocessA UI change shows before-and-after screenshots and says what a keyboard-only pass and a 200% zoom check found on the changed screens.
  • py-await-check-then-act blockcorrectnessWhen more than one worker or process can run, make check-then-act an atomic DB statement or constraint, because a Python lock covers one process only.
  • py-cancellation blockreliabilitycorrectnessRe-raise CancelledError (do not catch it via bare except or BaseException), and catch TimeoutError outside the asyncio.timeout() block.
  • py-class-earns-its-instance discussmaintainabilityGive a class real state or a collaborator; otherwise write a module function.
  • py-docstrings-google discussmaintainabilityWrite a Google-style docstring only when it adds what the signature cannot say.
  • py-error-hierarchy should-fixcorrectnessGive each package one base exception, with the specific ones in an errors module.
  • py-field-only-when-adds discusscorrectnessUse Field() only when it adds something (a constraint, an alias, or API docs), and set plain defaults directly.
  • py-frozen-dataclass-over-tuple should-fixcorrectnessReturn a @dataclass(frozen=True, slots=True) instead of a positional tuple.
  • py-httpx-client-lifespan should-fixperformancePass an explicit httpx.Timeout to every httpx client.
  • py-imports should-fixmaintainabilityPut imports at module top, absolute only.
  • py-init-assign-only should-fixmaintainabilityKeep __init__ and __post_init__ to assignments, and do I/O in a @classmethod factory.
  • py-init-py-empty should-fixmaintainabilityKeep __init__.py empty unless it re-exports the public API.
  • py-modern-typing should-fixcorrectnessWrite X | None and builtin generics, not typing aliases.
  • py-no-cast should-fixcorrectnessDo not use cast(); parse the boundary into a typed model, or narrow with isinstance.
  • py-no-init-or-model-tests should-fixtestingCover __init__ and plain models through the behaviour that uses them.
  • py-no-silenced-diagnostics should-fixmaintainabilitySuppress a Python diagnostic only with a single named code and a reason on the same line.
  • py-paths-from-file should-fixcorrectnessResolve paths from __file__, not the current working directory.
  • py-pydantic-validation should-fixcorrectnessValidate request data with a pydantic model, not hand-written checks.
  • py-pytest-parametrize should-fixtestingUse @pytest.mark.parametrize for test variations.
  • py-ruff-gate should-fixmaintainabilityEnable the Ruff rule sets E, F, I, B, UP, SIM, BLE, TID and D in CI.
  • py-settings-pydantic-settings should-fixmaintainabilityLoad env config with BaseSettings from pydantic_settings.
  • py-strenum-not-strings should-fixcorrectnessUse StrEnum for fixed string sets and HTTPStatus for HTTP codes.
  • py-task-reference blockcorrectnessNever discard the result of create_task; keep a reference and surface its exceptions, preferably through a TaskGroup.
  • py-test-hygiene discusstestingFreeze time and block network in tests.