Concerns

Last updated 2026-11-06

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, topic, or level. The picks go in the address, for example ?concern=security,performance&level=function, so you can share the view. Add .md or use cards.json for the same view as text or JSON.

How to report each check

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.

Verdict: request changes - change, function - 2 block, 1 should-fix FAIL, 1 PASS, 14 N/A
FAIL [block] chg-expand-contract - src/a.py:42 - renames the column and drops the old one in one migration
FAIL [block] svc-sqli-authn - src/db.py:88 - proven: builds the WHERE clause with an f-string from request.args
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: 14 cards, applies_when does not hold

Filters

Concerns

Levels

Topics

Group by

Checklist

CardSeverityConcernsRule
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-adr discussmaintainabilityprocessKeep a short written record for each significant design choice (datastore, framework, deviation from a pattern) that states the context, the decision, and its consequences.
code-build-hermetic should-fixprocessBuild from declared inputs only, so that the same source revision gives the same artifact.
code-ci-gates should-fixprocessRequire review and passing build, tests, lint, and type checks on the default branch before merge, and leave nothing mechanical to reviewer vigilance.
code-consistency-drift discusscorrectnessmaintainabilityFor each recurring concern (errors, config, HTTP clients, logging), make one pattern the standard instead of leaving several as equal peers.
code-dead-code should-fixmaintainabilityDelete unreferenced functions and variables, and the branches of expired feature flags.
code-dependency-licence-sbom should-fixsecurityGenerate an SBOM, and scan dependencies for known vulnerabilities on every change or on a schedule. Each ask is judged separately: name which one failed on the FAIL line.
code-dependency-pinning blocksecurityCommit a lockfile with hashes and install from it in CI.
code-docs-refs-resolve should-fixmaintainabilityRun a link check in CI over the docs, so that every relative link and anchor they cite resolves.
code-file-lines-ceiling discussmaintainabilityprocessSet a file-length limit in the linter (Pylint and SonarSource default to 1,000 lines), keep hand-written files under it unless a listed exception says otherwise, 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-perf-budget-in-ci should-fixperformanceprocessWrite the performance budget down as a CI check that fails the build when it is exceeded.
code-release-gated-on-ci should-fixreliabilityprocessMake a release or publish job depend on the checks passing for the tagged commit, never on the tag alone.
code-rule-has-enforcer should-fixmaintainabilityBack each written repo rule that a type, lint or CI check could enforce with that check, not with a line in an instruction file or a repeated review comment.
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.
code-secret-scan blocksecurityprocessScan for committed credentials, and treat any hit as leaked: revoke and replace it first. With no scanner present and no secret found, the FAIL is the missing control; evidence is "absent in <paths>". A platform scanner (GitHub secret scanning with push protection, GitLab secret detection) counts when it is enabled on the repo and covers history.
code-test-fixtures-built-once should-fixtestingperformanceBuild an expensive fixture once per test run, and reset state between tests with a rollback or a truncate, never a rebuild.
code-test-selection-on-pr discusstestingperformanceprocessWhen the full suite is slower than the pull-request feedback target, run only the tests the change affects on the pull request, and run the full suite before deploy or on a schedule.
code-vuln-remediation-window should-fixsecurityprocessWrite down how long a known-vulnerable dependency may stay unfixed and fix or upgrade it inside that window.
code-workflow-supply-chain blocksecurityprocessPin every CI action to a full commit SHA, and keep code from an unreviewed change out of any job that holds secrets or can deploy.
code-workload-identity should-fixsecurityExchange the platform's OIDC token for a short-lived cloud credential, and pin the trust policy to the workload.
fn-aria-role-has-state-and-keys should-fixaccessibilityWhen a native element cannot do the job, give the custom widget the state attribute and the keys its role promises.
fn-bool-arg-at-callsite discussmaintainabilityReplace a boolean flag argument with an enum, keyword-only argument or two functions.
fn-bounded-read-fails-at-cap should-fixcorrectnessreliabilitysecurityWhen a size cap is reached, return an error; never hand back the first N bytes as if they were the whole input.
fn-colour-not-sole-cue should-fixaccessibilityusabilityPair every colour that carries meaning with a second cue: text, an icon, a shape, or an underline.
fn-comments-explain-why should-fixmaintainabilityWrite comments that give a reason, a constraint, or a trade-off, and never restate what the next line does.
fn-comments-survive-context should-fixmaintainabilityWrite comments that remain true without outside context: no "currently", "for now" or "see the PR", and give a TODO the date or event that ends it.
fn-confine-file-path blocksecurityResolve the final path and check that it stays inside the intended base directory before using it.
fn-constant-time-secret-compare should-fixsecurityCompare a secret, token or MAC with the platform's constant-time function, never with == or !=.
fn-csprng-for-secrets blocksecurityDraw every security-relevant random value from the platform CSPRNG.
fn-destructive-confirm-or-undo should-fixusabilityMake a destructive action reversible with undo, or ask the user to confirm it before it runs.
fn-dialog-focus-managed blockaccessibilityusabilityWhen a modal opens, move focus into it and keep Tab inside it. Make Escape close it.
fn-disclosure-hides-only-secondary should-fixusabilityDo not hide a required field or information most users need behind a disclosure that starts closed.
fn-distinct-types-for-ids should-fixcorrectnessGive arguments with different meanings distinct types, so a call that swaps them fails to type-check.
fn-english-identifiers discussmaintainabilityWrite identifiers and comments in English, unless the project policy names another language.
fn-error-says-what-and-how should-fixusabilityaccessibilityShow each validation error next to its field, in plain words that name what is wrong and how to fix it.
fn-fetch-only-needed-data should-fixperformanceFilter, count, and aggregate in the query, and select only the columns the code uses.
fn-focus-indicator-visible blockaccessibilityusabilityKeep a visible focus indicator on every focusable element. Never set outline: none without a replacement.
fn-form-control-has-label blockaccessibilityusabilityTie every form control to a visible <label>, with for and a matching id or by wrapping it. A placeholder is not a label.
fn-guard-uri-decoding should-fixreliabilitycorrectnessWrap decodeURIComponent on user input in a try/catch, or parse with URLSearchParams, so that a malformed % sequence cannot throw.
fn-handle-rejected-promises should-fixreliabilitycorrectnessHandle the rejection of every promise you start: await it inside try/catch, end the chain with .catch(), or return it to a caller that does.
fn-header-value-encoding blocksecuritySet every response header through the framework's header API, never by writing to the connection, and reject or encode CR and LF in any request-derived value.
fn-heading-structure should-fixaccessibilityusabilityMark every heading with a real <h1> to <h6> element, not a styled div, span, or p.
fn-img-alt-text should-fixaccessibilityGive every <img> an alt attribute: text that serves the image's purpose, or alt="" when the image is decorative.
fn-independent-work-concurrent should-fixperformancecorrectnessStart independent I/O together and wait for all of it; run calls in sequence only when one needs the result of another.
fn-join-dont-concat-in-loop should-fixperformanceBuild a string from a loop with a builder or a join, never with repeated +=.
fn-jwt-verify-pinned blocksecurityVerify the signature against a fixed list of accepted algorithms, and check iss and aud, before reading any claim.
fn-keep-input-on-error should-fixusabilityAfter a failed validation or submit, show the form again with every value the user entered, correct or not.
fn-label-above-field discussusabilityaccessibilityPut the visible label of a text input, select, or textarea directly above it.
fn-length-budget discussmaintainabilitySplit a function that passes the project's length limit (about 40 lines if it sets none) unless its body is one simple operation or one flat dispatch.
fn-link-url-scheme-allowlist should-fixsecurityParse a URL that comes from data and allow only https: (and http: or mailto: where needed) before you set it as a link target.
fn-mask-credentials-in-output should-fixsecurityusabilityMask credentials in list, show and debug output (keep only the last four characters), and print a full value only behind an explicit flag.
fn-name-intermediate-conditions discussmaintainabilityName each compound condition by assigning its sub-conditions to booleans that say what they mean.
fn-native-button-or-link blockaccessibilityusabilityUse <button> for an action and <a href> for navigation. Do not attach a click handler to a div, span, or a with no href.
fn-no-blocking-call-in-async-code blockperformancecorrectnessNever make a blocking I/O call or run long CPU work directly in async code; use the async API or hand the work to a thread or worker.
fn-no-caller-mutation should-fixcorrectnesstestingDo not mutate a parameter or an object the caller owns, unless the function is documented as mutating it.
fn-no-check-then-act-across-await should-fixcorrectnessMake 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, 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-mass-assignment blocksecurityBind request data to a DTO or an explicit field allowlist, never straight onto the model.
fn-no-native-deserialise-untrusted blocksecurityParse untrusted input with a data-only format, never with a native object deserialiser.
fn-no-positive-tabindex should-fixaccessibilityusabilityWrite the DOM in reading order and never set tabindex above 0.
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.
fn-no-raw-html-sink blocksecurityWrite untrusted text through an encoding sink (textContent, auto-escaped template), never through a raw HTML sink.
fn-no-shell-with-input blocksecurityStart processes with the program and each argument as separate list items, and never through a shell string.
fn-object-level-authz blocksecurityCheck that the caller may act on the specific record before returning or changing it.
fn-parameter-limit should-fixmaintainabilitySet a parameter-count limit in the project's linter, and keep signatures within it.
fn-password-slow-hash blocksecurityHash passwords with Argon2id (or scrypt, bcrypt, PBKDF2) and a per-password salt from the library.
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-reduced-motion-respected should-fixaccessibilityusabilitySwitch off or replace large, repeating, or interaction-triggered motion when prefers-reduced-motion: reduce is set.
fn-regex-compiled-once should-fixperformanceCompile a regular expression once, at module or startup level, and reuse it.
fn-related-controls-in-fieldset should-fixaccessibilityusabilityWrap each radio group, checkbox group, and multi-part value, such as day, month, and year, in a <fieldset> with a <legend> that names the group, often as the question.
fn-rerun-safe-after-crash should-fixreliabilityMake a state-changing operation give the same result on a second run and after a crash at any step, by deriving each step from current state and making leftovers recognisable as stale.
fn-response-fields-explicit should-fixsecuritycompatibilityReturn a response type that lists each field, never the stored model or a generic dump of it.
fn-specific-exceptions-only should-fixcorrectnessCatch only the specific exception you can handle in business code.
fn-status-announced-live-region should-fixaccessibilityusabilityAnnounce an async status message through a live region (role="status" or role="alert"), and put a role="status" or aria-live region in the markup before its text changes.
fn-target-size should-fixaccessibilityusabilityMake each pointer target at least 24 by 24 CSS pixels, or space it so that a 24 px circle centred on it touches no other target and no other undersized target's circle.
fn-test-behaviour-not-implementation should-fixtestingmaintainabilityAssert what a caller can observe through the public interface, so a change that keeps behaviour does not break the test.
fn-test-oracle-independent should-fixcorrectnesstestingTake a test's expected value from the requirement, not from the code under test.
fn-tls-verify-on blocksecurityLeave certificate and hostname verification on in every environment that ships.
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 external entity resolution turned off, for example through a hardened parser such as defusedxml.
inc-perf-fix-has-profile-evidence should-fixperformancetestingTie the performance fix to evidence that names the bottleneck: a profile, a trace, or a USE check.
inc-rollback-path-tested should-fixreliabilityExercise each mitigation that a runbook names (rollback, failover, flag off) on a regular schedule.
mod-behaviour-lives-with-state discussmaintainabilityPut the invariants and calculations that read only one object's fields on that object.
mod-bounded-fan-out discussmaintainabilitySet a limit on how many other types or modules one unit depends on, and split a unit that passes it.
mod-class-size-budget discussmaintainabilitySplit a class that passes the project's size limit for fields, public methods or lines, unless it is a data record.
mod-colour-tokens-meet-contrast should-fixaccessibilityusabilityMake every text and background token pair meet 4.5:1 (3:1 for large text), and every border, icon, and focus colour meet 3:1 against its neighbour.
mod-deep-modules discussmaintainabilityPrefer a small interface that hides its implementation, and add a member only when callers need it.
mod-derive-dont-duplicate should-fixcompatibilitymaintainabilityDerive a type, list or enum from the schema or list that owns it, or add a build check that fails when the two disagree.
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-fixmaintainabilityKeep a module's internals unimportable and untouched from outside it. A caller uses the public surface, not a private file or member.
mod-law-of-demeter discussmaintainabilityCall methods on your direct collaborators, and do not call a method on an object that another call returned (a chain of two or more getters).
mod-layers-point-inward should-fixmaintainabilityMake dependencies point inward: surface, then logic, then boundary.
mod-no-import-cycles should-fixmaintainabilityKeep the dependency graph between modules or packages acyclic, and break a cycle by moving the shared part into a third module that both depend on.
mod-no-import-side-effects should-fixtestingmaintainabilityKeep 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; hold it on an instance.
mod-no-shotgun-surgery discussmaintainabilityKeep one decision in one module, and when a single change needs edits in many classes, move the scattered parts together.
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-wrong-abstraction should-fixmaintainabilityInline an abstraction that has grown flags for its callers.
mod-one-name-per-concept should-fixmaintainabilityUse one name for one concept across the codebase.
mod-pooled-clients-built-once should-fixperformanceBuild pooled clients once at startup and reuse them.
mod-proto-enum-zero-unspecified should-fixcompatibilityGive every protobuf enum a zero value named <ENUM>_UNSPECIFIED with no real meaning.
mod-single-writer-per-state should-fixcorrectnessLet only one writer change a piece of state at a time, through a single owner, a queue that serialises the writes, or compare-and-swap, never by convention.
mod-vetted-crypto-only blocksecurityEncrypt with an authenticated mode such as AES-GCM, and never reuse a nonce under one key.
mod-yagni should-fixmaintainabilityprocessDo not build an abstraction or capability for a need that does not exist yet; add it when the need or a second use appears.
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-alerts-symptoms-golden-signals should-fixobservabilityPage on user-visible symptoms, such as error rate and latency, not on causes.
prod-canary-staged-rollout blockreliabilityRoll out in stages behind a canary, and abort by rule, not by judgment.
prod-kill-switch-fallback should-fixreliabilityMake a risky feature switchable off without a deploy, and exercise every fallback path in test or in production on a schedule.
prod-latency-slo-percentile should-fixperformanceobservabilityDefine latency SLOs and alerts on high percentiles, never on the mean.
prod-load-test-before-launch should-fixperformancereliabilityLoad test before launch, past the expected peak, with pass and fail thresholds written down.
prod-profile-on-demand discussperformanceobservabilityMake a CPU and memory profile of a production instance obtainable, through a continuous profiler or a private profile endpoint.
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.
svc-account-linking blocksecurityLink a federated identity to an existing account only after proving control of both, and key the link on the pair iss and sub, never on an unverified email or another profile claim.
svc-api-cache-control should-fixperformancesecuritySet an explicit Cache-Control on every response a cache may store, use private or no-store for user-specific data, add Vary for any request header that changes the body, keep the origin's Cache-Control authoritative at the edge (no minimum TTL or force-cache override), and decide cacheability by the response Content-Type, not the URL extension.
svc-api-conditional-writes should-fixcorrectnessReturn an ETag on reads and honour If-Match on writes, answering 412 when the entity tag is stale.
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-deprecation-sunset should-fixcompatibilityBefore removing an endpoint, mark it deprecated in the spec and send Deprecation and Sunset headers.
svc-api-documented-errors should-fixcorrectnesscompatibilityDocument every error status each operation can return, with a schema and one example.
svc-api-error-code-stable should-fixcompatibilityGive each error a stable machine-readable code that callers branch on, and never make them parse the message text.
svc-api-key-scope should-fixsecurityIssue each API key with the narrowest scopes and a bounded lifetime, and rotate or revoke it after any exposure.
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-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-versioning-policy should-fixcompatibilityWrite down one versioning scheme for the API, and ship no breaking change inside a version it has published.
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-auth-throttle-generic-errors blocksecurityLimit failed attempts per account, and return the same message and status code whether or not the account exists.
svc-authn-by-default should-fixsecurityRequire authentication on every route by default, and mark each public route by name.
svc-authz-central-deny-default blocksecurityRoute every request through one authorization layer that denies when no rule allows it.
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-bound-client-controlled-sizes should-fixsecurityCap every client-controlled size and count on the server: body bytes, string length, array items, page size and batch size.
svc-bounded-background-tasks blockreliabilitycorrectnessCap how many background tasks run at once, and never spawn one per input with no limit.
svc-cache-key-completeness blocksecurityKey every request input that can change the response, and strip any other request value before it reaches a cached body.
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-exit-codes-and-streams should-fixcorrectnessmaintainabilityExit non-zero when a command fails, and write results to stdout and errors and progress to stderr.
svc-cli-non-interactive should-fixmaintainabilityprocessLet the caller turn every prompt off with a flag or an environment variable, so the command never waits on a terminal.
svc-cors-allowlist should-fixsecurityAllow cross-origin access only to a fixed list of named origins, and never echo the request Origin header back unchecked.
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-csrf-state-changing blocksecurityRequire a CSRF token (or an equivalent header check) on every cookie-authenticated request that changes state, and never change state on GET.
svc-decompression-cap should-fixsecurityperformanceCap the decompressed output of every decoder, and set the cap on the output rather than the compressed input.
svc-dlq should-fixreliabilityGive every consumer queue a dead-letter queue and keep a way to replay it after the fix. On an ordered queue, key the group or session to the unit that must stay ordered, so a poison message holds only its own unit.
svc-export-scope blocksecurityScope an export to what the requesting principal may read.
svc-fail-closed-defaults should-fixsecurityShip every security control switched on, with an empty allow-list denying everything.
svc-host-header-trust blocksecurityBuild absolute URLs from configured values, answer only for a Host on an allowlist, and take X-Forwarded-* values only from a trusted proxy.
svc-idempotency-key blockreliabilitycorrectnessMake every retryable write idempotent: the caller sends a unique key, and a retry with the same key never applies the write twice.
svc-invalid-input-is-4xx should-fixcorrectnessreliabilityCheck each caller-supplied value against its allowed domain (range, allowed set, an id that must exist, an encoding the code can handle) at the boundary, and answer a failed check with a 4xx, never a 5xx.
svc-list-endpoint-paginates should-fixperformancePaginate every list endpoint, with a default page size and a server-side maximum.
svc-mfa-step-up should-fixsecurityRequire a fresh authentication with an already-bound factor before sensitive actions and before adding, replacing or removing an MFA factor; an existing session alone is not enough.
svc-no-redundant-entry should-fixusabilityaccessibilityDo not ask for information the user already gave in the same flow. Fill it in, or let the user pick it.
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-oauth-code-flow-binding blocksecurityFinish the authorization-code flow with PKCE and a challenge method that keeps the verifier out of the authorization request (S256), send the exact registered redirect_uri (a native app on the loopback interface may vary the port), and reject the response unless this transaction's state or OIDC nonce matches and the ID token's signature, iss, aud and exp check out.
svc-password-reset blocksecurityMake the reset token single-use and short-lived, and on success revoke every session.
svc-rate-limit-quota should-fixsecurityreliabilityEnforce a per-tenant quota on shared APIs and queues.
svc-reflow-and-zoom should-fixaccessibilityusabilityMake the page usable at 320 CSS pixels wide and at 200% text zoom, with no sideways scrolling, no clipped content, and no blocked pinch-zoom.
svc-request-framing blocksecurityReject a request that carries both Transfer-Encoding and Content-Length, or remove one field at the first hop, and parse header framing strictly rather than with a leniency flag.
svc-retry-policy blockreliabilityRetry only transient errors, with capped attempts and jittered exponential backoff.
svc-saga-steps should-fixreliabilitycorrectnessMake steps after the pivot idempotent and retryable, and make every compensation idempotent with a failure path.
svc-saml-assertion-binding blocksecurityVerify the XML signature over the assertion you read, with the IdP's configured key rather than a key carried in the response, then require the assertion's Audience and its bearer SubjectConfirmationData Recipient to name this SP, the response Destination to be this endpoint, InResponseTo to match your request (absent for an IdP-initiated response), NotOnOrAfter to be current, and the assertion ID to be unseen. These are one step, verify the assertion, and each check is cited.
svc-session-lifecycle blocksecurityIssue a new session ID at login, and set Secure, HttpOnly and SameSite on the session cookie.
svc-slow-operation-shows-progress should-fixusabilityaccessibilityShow that a slow action is under way, and show its progress when it runs long.
svc-soft-delete-default should-fixsecuritycorrectnessFilter soft-deleted rows out of every read path by default, and make a read that includes them an explicit call.
svc-sqli-authn blocksecurityPass untrusted data to queries as bound parameters, never by string concatenation or formatting.
svc-stream-dont-materialise should-fixperformanceProcess large results as a stream with backpressure; do not load them whole into memory.
svc-tenant-id-in-telemetry should-fixsecurityobservabilityPut the verified tenant id on every tenant-scoped log, metric and audit record.
svc-timeouts blockperformancereliabilitySet an explicit timeout on every remote call.
svc-tls-modern-only should-fixsecurityAccept only TLS 1.2 and TLS 1.3 on servers.
svc-update-rollback-on-failure should-fixreliabilityWhen an update fails, restore the previous version instead of leaving a missing or half-written one.
svc-update-verify-provenance should-fixsecurityVerify a downloaded update against a signature, an attestation or a pinned key, or against a checksum that reached you by another route than the file; a checksum fetched from the same host as the file does not count.
svc-upload-validate-store blocksecurityAllowlist the file type, cap the size, and store each upload under a generated name where the server will not execute it.
svc-webhook-replay-window should-fixsecurityReject an inbound signed message whose creation time is outside a short tolerance, and sign that time with the body so it cannot be swapped.
sys-agent-tool-least-privilege blocksecurityprocessGive the agent only the narrow tools and the minimal credentials its task needs.
sys-cache-bounds-invalidation should-fixperformanceBound every cache by size and give its entries an expiry.
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-consistent-ui-terms discussusabilityaccessibilityUse one label and one icon for the same action and the same concept across all screens.
sys-fanout-leg-deadlines should-fixperformancereliabilityGive every leg of a fan-out its own deadline, and decide in code what happens when a leg misses it: a partial result, a hedged request, or an error.
sys-health-liveness-readiness should-fixreliabilityWire load balancers and restarters to liveness and local checks only, never to shared-dependency checks.
sys-index-concurrently should-fixcompatibilityCreate indexes with CONCURRENTLY, outside a transaction block, and handle a failed build that leaves an INVALID index.
sys-load-shedding-bounded-queues blockreliabilityBound every queue and reject excess work cheaply.
sys-lock-fencing blockreliabilitycorrectnessCheck a correctness lock on the resource side (fencing token or compare-and-set), never by lock possession alone.
sys-migration-expand-contract blockreliabilitycompatibilityRun data backfills in batches, in a migration separate from the schema change.
sys-migration-lock-timeout should-fixcompatibilitySet lock_timeout for the migration session and retry on timeout.
sys-n-plus-one-pooling should-fixperformanceFetch related rows in one query or batch, never one query per row.
sys-pii-minimise-retention should-fixsecurityGive every store of personal or sensitive data a retention period, and delete or anonymise the data when it ends.
sys-prompt-injection blocksecurityValidate model output deterministically before code acts on it.
sys-secrets-and-errors blocksecuritycorrectnessFail closed: a validation or auth error must deny, never continue, and an error response must not carry internals such as stack traces, SQL or tokens.
sys-ssrf blocksecurityFetch a user-supplied URL only when its host matches a server-side allowlist.
chg-agent-grounded-code should-fixmaintainabilityprocessVerify 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-approval-tied-to-patch should-fixprocessTreat an approval or verification verdict as current only if the patch is unchanged: compare git patch-id at the verdict commit with the current head. If the patches differ only in tests, docs, or lint config, the verdict can stand when the built output is the same; any other difference needs a fresh check.
chg-author-hygiene should-fixprocessSelf-review the diff and write the description before requesting review.
chg-breaking-change-taxonomy blockcompatibilityTreat any change that callers can observe in a signature, return values, error types, defaults, or side effects as breaking until a consumer check says otherwise.
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-fixcompatibilityprocessFlag a change that renames or removes an environment variable, moves a secret, or remaps a port as breaking for developers and operators, and update every place that documents or sets it.
chg-expand-contract blockcompatibilityEvolve shared contracts in steps: add the new form beside the old (expand), migrate every consumer, then remove the old form (contract) in a later change.
chg-match-codebase-pattern should-fixcorrectnessmaintainabilityFollow the established pattern nearby.
chg-migration-add-column-rewrite should-fixcompatibilityAdd the column nullable or with a constant default, then fill volatile, computed, or identity values in batches.
chg-name-attack-surface should-fixsecurityprocessList any new attack surface in the description.
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-one-concern should-fixprocessMake each change do one logical thing; if the description needs "and" between unrelated outcomes, split it.
chg-perf-claim-evidence should-fixperformancetestingBack a performance claim with measured before-and-after numbers.
chg-proto-no-field-type-change should-fixcompatibilityNever 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 should-fixcompatibilityWhen 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-refactor-has-behaviour-pin should-fixtestingmaintainabilityPin current behaviour with a characterization test, snapshot or equivalence check before the refactor moves any structure.
chg-refactor-separate should-fixmaintainabilityprocessPut refactors, renames, and reformatting in their own commit or PR, apart from behaviour changes.
chg-reuse-before-write should-fixmaintainabilityDo not add a helper that duplicates one already in the repo; search for it first.
chg-review-signal discussprocessDo not spend review comments on what a tool enforces or on minor style points; spend them on the findings that matter.
chg-rollback-path should-fixreliabilityState in the description how to undo the change.
chg-size-ceiling discussprocessSplit a change past about 400 changed lines or about 20 files, or say in the description why not; aim for about 200.
chg-tests-ship-with-change blocktestingShip new or changed behaviour in the same change as a test that fails if the behaviour breaks.
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.
chg-verify-before-claim blocktestingprocessBack every "works" or "bug" claim with something run: a repro, a test or command output.
py-cancellation should-fixreliabilitycorrectnessRe-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-field-only-when-adds discusscorrectnessUse Field() only when it adds something (a constraint, an alias, or API docs), and set plain defaults directly.
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-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-paths-from-file should-fixcorrectnessResolve paths from __file__, not the current working directory.
py-pytest-expensive-fixture-scope should-fixtestingperformanceGive an expensive pytest fixture scope="session" or "module" and isolate each test with a rollback, never a schema build or a seed load inside a function-scoped fixture.
py-pytest-parametrize should-fixtestingWrite tests that differ only in inputs and expected values as one @pytest.mark.parametrize test.
py-ruff-gate should-fixmaintainabilityEnable the Ruff rule sets E, F, I, B, UP, SIM, BLE, TID and D in CI.
py-task-reference should-fixcorrectnessNever discard the result of create_task; keep a reference and surface its exceptions, preferably through a TaskGroup.
py-test-hygiene discusstestingreliabilityKeep unit tests off external I/O (the network, the shared filesystem and the database) and off the real clock, and run tests that need them in a separate, slower tier.
py-xdist-worker-isolated-state should-fixtestingreliabilityUnder pytest-xdist, give each worker its own database or other mutable resource, keyed by worker_id, and build an expensive shared one once with a lock file.

Back to filters

What the badges mean

blockmust be fixed before merge or release.
should-fixfix it, but it need not block.
discussraise it and decide together.
stablevetted; use for verdicts.
draftnot vetted; do not use for a verdict.
Tool gate: what a linter or CI check could enforce instead of a reviewer.

Draft cards

74 draft cards

A draft card is not vetted. Report a FAIL of one under Draft findings, at should-fix at most, never in the ledger or the verdict. Each row links to the full card. How a draft becomes stable

CardSeverityConcernsRule
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-fixmaintainabilityprocessKeep the setup, build and run commands in the README or contribution guide accurate: they work as written on a clean checkout, and any drift is fixed or reported.
code-test-suite-time-budget should-fixtestingperformanceprocessRecord the suite's total time and its slowest tests on every CI run, and fail the build when the total or a single test passes a written budget.
fn-atomic-related-updates should-fixcorrectnessMake related writes succeed or fail together.
fn-empty-collection-not-none should-fixcorrectnessReturn an empty collection for "nothing found"; return None only when absent differs from empty.
fn-known-keys-get-a-type should-fixcorrectnessGive a fixed key set a record type: a model, a dataclass or a typed dict.
fn-no-anonymous-tuples should-fixmaintainabilityReturn a small named record, not a positional tuple, once the fields differ in meaning.
fn-no-pass-through-wrapper should-fixmaintainabilityDelete a method that only forwards, and keep wrappers that validate, adapt, or narrow.
fn-no-stringly-typed-returns should-fixcorrectnesscompatibilityReturn a closed type (an enum, a tagged union or a sealed hierarchy) for a closed set of values, not a bare string. For a boolean flag, see fn-bool-arg-at-callsite.
fn-propagate-dont-swallow should-fixcorrectnessChain the original cause when you translate an exception.
fn-resource-lifetime should-fixcorrectnessGive every task and handle an owner that waits for it or closes it, on the error path too.
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.
inc-review-asks-which-check should-fixreliabilityprocessEvery incident review names the check that should have caught the fault (a test, CI gate, review, canary or alert) and turns the gap into a new or fixed check.
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-mock-at-boundaries-only should-fixtestingMock only at the process boundary (HTTP, DB, cloud, clock, I/O).
mod-no-repeated-switches discussmaintainabilityWhen the same switch or if-chain on one type appears in more than one place, replace the copies with polymorphism, unless each copy is an exhaustive switch over a closed type that fails the build when a case is missing.
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-prefer-sync-api discusscorrectnessKeep logic in plain synchronous functions with no I/O, and add async wrappers at the edge only.
mod-shim-fails-loudly should-fixcorrectnessreliabilitytestingA shim or stub must raise for every operation it does not implement; it must not return a success value such as 0, None or an empty result for an unknown call.
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-temporary-field discussmaintainabilityMake a field a local variable or a parameter when every method that uses it assigns it before reading it.
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-wide-events-bounded-labels should-fixobservabilityEmit one structured event per request carrying trace, tenant, build and flag state.
svc-api-safe-idempotent-methods should-fixcompatibilityKeep 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-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-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-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.
sys-append-only-stores-have-retention should-fixreliabilityperformanceGive every store that only grows (event, audit and history tables, log files, finished-job registries) a maximum age or count, and a job or setting that enforces it.
sys-cache-cold-start should-fixperformancereliabilityCap and coalesce the cache-miss path so an empty cache cannot overwhelm the origin.
sys-constraint-not-valid should-fixcompatibilityAdd the constraint NOT VALID, then run VALIDATE CONSTRAINT in a separate step, and never leave the VALIDATE out.
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.
chg-agent-mock-asserting-tests should-fixtestingprocessWrite 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-bot-approval-not-human should-fixprocesssecurityDo not let a bot or agent approval satisfy a required human approval.
chg-fix-root-cause-not-symptom should-fixcorrectnesstestingIn 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 should-fixprocessTrace every behaviour change in the diff to the stated requirement, and flag missing requirements and any change nobody asked for.
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-per-user-ide-files should-fixprocessmaintainabilityDo not commit a file that holds one developer's editor or IDE state; ignore those paths in the repository or a machine-wide exclude file, and keep the settings the team shares in the repository.
chg-review-comment-format discussprocessLabel each review comment with its severity: block, should-fix, or discuss.
chg-review-rigour-by-risk should-fixprocessSet the review tier from what the change touches, such as auth, billing, CI or release workflows, and not from who wrote it.
chg-review-rounds-capped discussprocessCap the number of review rounds; after the cap, re-review only the new diff and ask the author to rethink the approach if findings keep coming.
chg-review-threads-resolved should-fixprocessDo not merge while any review thread is open; each one ends as a fix or as a resolution with a stated reason.
chg-sensitive-paths-human-owner should-fixsecurityprocessName a human owner in CODEOWNERS for auth, billing, CI and release paths, and require that owner's approval.
go-govulncheck-in-ci should-fixsecurityRun govulncheck ./... in CI and fail the build on a reported vulnerability that your code calls.
go-http-client-timeout should-fixreliabilityperformanceNetwork calls carry a deadline: a context.Context passed to NewRequestWithContext, or an http.Client with Timeout, never http.DefaultClient without either.
go-mod-readonly-verified should-fixsecurityreliabilityCommit go.sum, build in CI with -mod=readonly, and run go mod verify.
go-no-init-side-effects discussmaintainabilitycorrectnessinit() does no I/O, reads no environment and does not depend on other init() functions; do that work from main().
go-test-race-in-ci should-fixcorrectnessreliabilitytestingCI runs the test suite with go test -race ./....
go-vet-lint-gate should-fixcorrectnessmaintainabilityCI runs go vet and a linter set that includes staticcheck and errcheck, and a finding fails the build.
go-wrap-errors-with-w should-fixcorrectnessreliabilityCheck every returned err; when you add context, wrap with fmt.Errorf("...: %w", err) unless the cause must stay hidden.
py-await-check-then-act should-fixcorrectnessWhen 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-error-hierarchy should-fixcorrectnessGive each package one base exception, with the specific ones in an errors module.
py-frozen-dataclass-over-tuple should-fixcorrectnessReturn a @dataclass(frozen=True, slots=True) instead of a positional tuple.
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-no-silenced-diagnostics should-fixmaintainabilitySuppress a Python diagnostic only with a single named code and a reason on the same line.
py-pydantic-validation should-fixcorrectnessValidate request data with a pydantic model, not hand-written checks.
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-test-collection-and-imports discusstestingperformanceSet testpaths in the pytest configuration.
typescript-mock-at-the-boundary should-fixtestingmaintainabilityFake the system boundary (network, clock, storage), for example with Mock Service Worker; do not vi.mock your own modules when a boundary fake would do.
typescript-no-floating-promises should-fixcorrectnessreliabilityEvery Promise is awaited, returned, or given a .catch; enable @typescript-eslint/no-floating-promises.
typescript-partial-mock-keeps-original should-fixtestingcorrectnessA vi.mock factory spreads await importOriginal() and overrides only what the test needs; never swap an exported error class for a stub.
typescript-shared-test-setup discusstestingmaintainabilityPut setup that every test file repeats into one file listed in setupFiles, not into each test file.
typescript-strict-mode should-fixcorrectnessmaintainabilitytsconfig.json sets "strict": true; switch off a single strict flag only with a written reason.