05 / Checklists
A calm sequence for the first ten minutes.
Focused incident checklists that identify safe evidence, false assumptions, stop conditions, and proof-of-fix criteria.
Authentication cookie debugging checklist
A focused checklist for engineers when the browser fails to persist or send the session cookie required by the server. The guide sequences DevTools observation, Set-Cookie attribute analysis, storage boundary inspection, and request/response correlation so each competing cause—SameSite, Secure, Path/Domain, expiration, size, and client blocking—can be ruled in or out with named evidence.
Open guide →Cache consistency debugging checklist
Investigate and resolve cache consistency failures where readers observe values that disagree with the source of truth. This checklist covers stale-read detection, TTL verification, invalidation boundary tracing, and regression checks grounded in HTTP Cache-Control semantics.
Open guide →CI-only failure debugging checklist
A diagnostic checklist for CI-only test failures where the pipeline check passes locally on a developer's machine but fails inside the remote runner. The guide frames the runner as a separate boundary with its own OS image, filesystem state, secrets, and environment, and walks through ordered triage steps to localize the divergence before changing code.
Open guide →Container network debugging checklist
A practical Docker container network debugging checklist for the failure mode "a container cannot reach the intended service or is reached on the wrong address." It sequences a triage from a single failing container outward to network driver, DNS, and published-port boundaries, with concrete commands and observable pass/fail criteria at each step. The guide emphasizes evidence-conditional decisions rather than generic advice, and uses read-only Docker commands scoped to the affected container and network.
Open guide →Database lock-wait debugging checklist
A focused PostgreSQL lock-wait debugging checklist for backend and database engineers. Walks through recognizing blocked sessions, reading pg_locks and pg_stat_activity safely, distinguishing transaction-level from tuple-level waits, identifying the blocking holder, and applying conditional, evidence-based mitigations without destructive operations.
Open guide →502 incident debugging checklist
On-call checklist for triaging HTTP 502 Bad Gateway incidents at proxy or load balancer boundaries, with ordered evidence collection, scope isolation between client, proxy, and upstream, and conditional mitigations tied to observable proof.
Open guide →Production environment drift debugging checklist
Production environment drift is a deployment contract failure: the running service no longer matches the reviewed manifest, IaC declaration, or build artifact the release engineer signed off on. This checklist helps release engineers move from observable evidence (works in staging, fails only in production) to a verifiable cause without destructive actions, using read-only inspection of the live target, declarative drift detection, and immutable artifact digests.
Open guide →Background worker stall debugging checklist
A debugging checklist for background queue workers that begin a job but never reach a terminal state (completed or failed). Covers stall detection signals, lock lifetime boundaries, and the order of triage steps an on-call engineer should follow before attempting any fix.
Open guide →API 429 diagnosis checklist
A focused diagnostic checklist for HTTP 429 Too Many Requests responses: how to confirm the failure boundary, separate client retry behavior from server quota enforcement, and verify a fix without relaxing real rate limits. The guide covers header-level evidence (Retry-After, RateLimit-*), causes such as burst window collisions, token bucket exhaustion, per-API-key quotas, and CDN/WAF throttles, plus a verification path that distinguishes a true quota from a misconfigured middleware.
Open guide →API 502 diagnosis checklist
An editorial analysis of HTTP 502 Bad Gateway failures as evidence of a broken upstream contract between a gateway/proxy and the origin it depends on. The piece argues that 502 is not a bug to patch but a boundary symptom, and presents a triage checklist grounded in what the response actually carries: the gateway identity, the upstream hop, and the timing window. Readers should leave able to distinguish upstream reachability, transport, protocol, and timeout causes from a single 502 sample and its surrounding evidence.
Open guide →API client connection-pool checklist
A practical blog-style checklist for diagnosing exhausted or non-returning outbound HTTP connection pools. Each item is tied to an observable signal so a beginner can decide whether the client, the pool configuration, or the calling code is responsible, before changing limits or retry behavior.
Open guide →API timeout diagnosis checklist
An editorial analysis of HTTP API timeout failures framed as a working diagnosis checklist. The piece argues that most API timeout incidents are misclassified at the first observation, and that disciplined boundary mapping, deadline accounting, and evidence-conditional responses are required to separate client, proxy, and upstream causes before any remediation is attempted.
Open guide →Browser heap-growth checklist
A practical triage checklist for engineers facing browser heap usage that climbs with each repeated workflow. This guide frames heap growth as an evidence problem, not a vibes problem: you collect measurements before mutating any code path, then attribute growth to a specific boundary (allocation site, retention path, or detached DOM) using Performance, Memory, and Heap Snapshot tooling from MDN.
Open guide →Browser performance checklist
Engineers frequently chase browser performance problems as if they were a single defect, when in practice input handling, navigation timing, and rendering each consume a separate share of the interaction budget. This guide frames browser performance as a budget-allocation problem, gives an ordered triage that measures where the budget is actually being spent, and pairs each diagnostic branch with a conditional fix and a regression check that can be re-run. The central argument: stabilize the budget you can measure before touching the code you suspect.
Open guide →Session-cookie checklist
A Session-cookie checklist for engineers diagnosing authentication failures where browser sessions disappear or fail to reach the server. The guide frames a clear argument: most session loss is not a "session bug" but a contract mismatch between the cookie the browser sends and the request the server accepts, so triage must verify attributes, scope, transport, and storage before changing application code. Use it when users report being signed out unexpectedly, when authenticated requests return 401/302 to login, or when a SameSite or Secure change silently drops cookies.
Open guide →CSRF validation checklist
A field-tested CSRF validation checklist for engineers debugging state-changing requests that fail token or origin checks. Walks through observable symptoms, the boundary between server-side validation and credential transport, diagnostic steps that separate SameSite, double-submit, and synchronizer-token failures, and proof-of-fix regression criteria grounded in HTTP cookie semantics.
Open guide →Deployment reachability checklist
A deployment reachability checklist for engineers who confirm a build succeeded but the application is not serving reachable traffic. The guide converts a 502-class symptom (origin not producing valid responses behind ingress or load balancer) into an ordered triage boundary map, then into conditional safe fixes keyed to evidence. It treats Deployment reachability as a contract between image availability, port exposure, readiness gating, service routing, and external ingress, and shows how to prove each link before changing configuration.
Open guide →Deployment rollback checklist
Deployment rollback checklist for engineers who must safely and provably return a service to the previous version after a release shows regressions. Covers pre-rollback evidence collection, decision gates, the rollback action itself, and post-rollback verification. Anchors to observable HTTP-layer behavior so success or failure can be demonstrated without depending on internal tooling claims.
Open guide →Distributed-lock checklist
A distributed-lock playbook for engineers diagnosing ownership anomalies such as stale holders, contested locks, or lock renewal continuing after the holder's liveness signal has been lost. Provides a triage-first sequence, boundary-specific evidence to collect, and conditional mitigations that depend on observable proof rather than guesswork.
Open guide →Docker port-binding checklist
Docker port-binding checklist that turns an unreachable container or host-listener conflict into a documented, evidence-driven decision. The piece argues that most "port not working" symptoms are not network problems at all but binding-scope, port-already-in-use, or firewall ordering mistakes, and walks through the exact boundaries an engineer must inspect before changing configuration.
Open guide →Docker volume checklist
A beginner-oriented blog diagnosing why container data goes missing, becomes shadowed, or fails to persist despite running containers. Walks through observable evidence such as empty working directories after restart, writes that vanish on `docker run` reload, and bind-mount paths that mismatch container expectations. Frames volume inspection as a deliberate decision: anonymous vs named volumes, bind mounts vs tmpfs, UID/GID ownership, and driver semantics governed by the `docker run` reference rather than assumed defaults.
Open guide →GitHub Actions artifact checklist
Operational playbook for diagnosing GitHub Actions jobs that cannot exchange build output through the artifacts mechanism. Treats artifacts as a contract between jobs (name, path, retention, permissions) rather than a passive upload, and sequences decisions from symptom to proof. Each step names the boundary being checked, the evidence that distinguishes competing causes, and the safe action conditional on that evidence.
Open guide →GitHub Actions permission checklist
A beginner playbook for verifying GitHub Actions permissions when a workflow step fails because it lacks a token or runner permission. It walks engineers from the first error line through reading the workflow YAML, mapping the GITHUB_TOKEN scopes, checking job-level and workflow-level permissions, and confirming the runner context, then closes with a re-run that proves the fix.
Open guide →Graceful-shutdown checklist
A practical graceful-shutdown checklist for Node.js services: how to stop accepting new work, drain in-flight requests, close database and message-broker connections, and exit with a defined code, while verifying each phase with observable evidence. Treats shutdown as a sequence of bounded waits with timeouts rather than a single signal handling step.
Open guide →GraphQL null-field checklist
This playbook gives advanced GraphQL engineers an operational checklist for diagnosing fields that return null unexpectedly inside a partial response, rather than as part of a top-level errors array. It focuses on the contract defined by the GraphQL October 2021 specification around null propagation and field-level error handling, and translates it into decision points a debugger can follow without guessing.
Open guide →JWT expiry checklist
A practical debugging checklist for engineers chasing JWT expiry bugs where tokens are accepted or rejected at unexpected time boundaries. The argument: expiry bugs are rarely about the exp claim itself; they live at the seams between issuer clock, system clock, leeway configuration, clock skew, and the boundary where the verifier evaluates the exp/nbf/iat triplet. This guide walks triage from the first observable symptom to a regression-grade proof of fix, anchored to HTTP Set-Cookie behavior and JWT structural rules.
Open guide →Kubernetes CrashLoopBackOff checklist
A structured triage checklist for Kubernetes CrashLoopBackOff, distinguishing container startup crashes from passing-but-unhealthy probes. Walks through ordered evidence gathering, log boundaries, manifest review, and safe mitigation actions tied to observable proof criteria.
Open guide →Kubernetes service-routing checklist
Edge-aware triage checklist for diagnosing a Kubernetes Service that fails to route requests to intended ready Endpoints, organized as a blog-style argument that defends each decision rather than listing commands in isolation. The guide argues that routing failure is a boundary problem first, not a pod problem, so verification must walk the Service selector, Endpoints slice, kube-proxy data plane, and DNS contract before any workload restart.
Open guide →Logging evidence checklist
A practical checklist for collecting and verifying the minimum logging evidence required to attribute a failure to a specific request, attempt, or system boundary. Engineers use this guide when logs exist but do not explain which entity, request ID, or boundary crossing was responsible for the observed failure.
Open guide →Lost-update checklist
A practical, evidence-driven lost-update checklist for diagnosing cases where a later write silently overwrites a concurrent change in a relational database. The guide frames lost updates as a concurrency-control failure, not a logic bug, and sequences symptom capture, isolation-level verification, and lock-trace correlation before any code or schema changes are proposed. It is written for engineers who already have a reproducible case in hand and need a conservative triage path that distinguishes optimistic-concurrency failures, read-committed anomalies, and missing row locks.
Open guide →OAuth callback checklist
A practical OAuth callback checklist for engineers diagnosing cases where the authorization callback fails to restore the initiating session. Walks through ordered triage of redirect URI matching, state parameter binding, cookie attributes, and PKCE binding before any code change, so the fix is anchored to evidence rather than guesswork.
Open guide →Observability-correlation checklist
A beginner-friendly checklist for verifying that logs, metrics, and traces emitted by a service share the same correlation identifiers and can be joined back to a single request or transaction. The guide frames correlation as the discipline of propagating identifiers end-to-end so an engineer can pivot from a trace span to its log lines and metric points without manual stitching.
Open guide →OpenTelemetry trace-continuity checklist
A grounded OpenTelemetry trace-continuity checklist for verifying that a single logical transaction stays correlated across HTTP boundaries, async/queue hops, and process boundaries. Use this guide when distributed traces arrive in the backend as multiple unrelated trace IDs, gaps appear in the trace timeline, or propagation headers are missing or stripped by an intermediary.
Open guide →PostgreSQL CTE performance checklist
A practical PostgreSQL CTE performance checklist for engineers diagnosing unexpected work introduced by Common Table Expressions (WITH queries). Covers planner behavior, the WITH ... MATERIALIZED vs inline boundary, predicate pushdown limits, recursion cost, and the diagnostic sequence for proving a CTE is the actual regression source rather than a coincidental plan change.
Open guide →PostgreSQL connection-pool checklist
A practical checklist for engineers diagnosing PostgreSQL failure surfaces where application requests queue waiting for pooled database connections. Walks through observable pool exhaustion symptoms, evidence boundaries between the application pool and the PostgreSQL backend, and verification criteria before changing pool size or query behavior.
Open guide →PostgreSQL replica-lag checklist
PostgreSQL replica-lag checklist for engineers whose read replicas are falling behind the primary write stream. Walks through what to observe in pg_stat_replication and pg_stat_subscription, how to decide whether the bottleneck is network, disk, replay, or apply-side, and the safe, read-only verification steps to confirm recovery before reopening traffic.
Open guide →PostgreSQL slow-query checklist
A structured triage checklist for diagnosing PostgreSQL queries that exceed their expected latency. It separates plan-driven, wait-driven, and storage-driven slow-query behavior, and prescribes evidence-led verification before any change. Scope: a single query or small query set, not server-wide tuning.
Open guide →Queue retry checklist
A bounded, observable queue retry checklist for engineers diagnosing jobs that retry indefinitely or fail without a visible recovery path. The playbook sequences evidence collection, stall/timeout classification, retry policy verification, and dead-letter containment using explicit decision points grounded in BullMQ stalled-job semantics.
Open guide →Queue stall checklist
A short operational playbook for diagnosing stalled jobs in BullMQ-based queues, where workers fail to acknowledge progress or completion and the jobs sit in an "active" state without forward motion. The guide focuses on observable evidence, narrow cause elimination, and conditional remediation steps that depend on verified facts rather than assumptions.
Open guide →Race-condition checklist
A field-ready checklist for diagnosing race conditions in distributed systems, organized as a decision-flow playbook. Each step names what to observe, which boundary to inspect, and what the result means before any code or config change is considered. Verification criteria are explicit so a finding can be reproduced or refuted.
Open guide →React memory-retention checklist
Repeated interaction with a React component retains work it should have released: closures, subscriptions, timers, and references survive unmount or re-render. This checklist gives advanced engineers an evidence-driven triage path grounded in React's documented effect semantics, separating user-perceived jank from measurable retention so fixes can be proven rather than asserted.
Open guide →React render-loop checklist
A practical blog-style checklist for diagnosing React render loops, organized around an editorial argument: confirm the loop is real, isolate which update channel is rescheduling renders, then fix the smallest root cause and verify with a regression check.
Open guide →Reproducible-build checklist
This guide gives advanced engineers a reproducible-build checklist for diagnosing cases where the same commit produces different artifacts. It focuses on observable symptom classes, where to draw verification boundaries in a build graph, and how to use Turborepo's caching contract as the reference model for expected behavior. The aim is to isolate uncontrolled inputs that break determinism before chasing compiler or toolchain versions.
Open guide →Turborepo cache checklist
Turborepo caches task output by hashing inputs (sources, env, dependencies) and outputs. When a task reports cache misses, partial hits, or stale results, the root cause is almost always that the task definition is missing inputs that actually affect its output. This checklist enumerates what to inventory in a `turbo.json` `pipeline` task before trusting any cache hit, ordered so the cheapest, most decisive checks come first. The guide targets Turborepo v1/v2 declarative `pipeline` tasks; `turbo.json` is the only configuration source of truth for the cache key.
Open guide →Turborepo CI-cache checklist
A practical debugging checklist for engineers when Turborepo's local cache and CI cache behave differently, covering cache key inputs, remote cache authentication, environment hashing, and verification steps to isolate whether divergence is caused by inputs, the cache layer, or environment drift.
Open guide →Vite import-resolution checklist
A diagnostic checklist for engineers when a Vite module resolves correctly in one mode (dev, build, SSR, or preview) but fails in another. The guide frames the failure as a boundary mismatch between request contexts, base path assumptions, and import-graph metadata, and provides a triage sequence keyed to Vite's resolve pipeline, environment-specific options, and dependency pre-bundling.
Open guide →Vite stale-output checklist
A practical, evidence-driven Vite stale-output checklist for engineers who see the dev server serving transformed output from an old dependency graph. The guide walks through observable symptoms, an ordered first-ten-minutes triage, named boundaries to inspect, and conditional fixes tied to specific proof-of-fix checks, all anchored to the official Vite guide.
Open guide →Worker acknowledgement checklist
A playbook for verifying that work is acknowledged at the correct durability boundary in a BullMQ queue, distinguishing between runtime execution completion and persistent state acknowledgement. Use when jobs report completed in application telemetry but reappear, stall, or get reprocessed after restart, or when stalled job recovery runs against still-executing workers.
Open guide →