Debugging
Finding and fixing the cause of a defect, crash or failing build.
Download all 103
Start here 2
The general, start-from-zero entry for a need in this category: it works from a blank start, asks for what it needs and hands off to the specific entries. Example: Plan a trip.
- Fix a bug
Fixes a bug from a symptom or error, asking what happens, what should happen and how to trigger it if missing, then reproduces it, fixes the cause and proves it. Start here for any bug.
- Debugger
Debugs by reproducing first, testing one hypothesis at a time and fixing root causes, never symptoms. Use as a persona or subagent for bugs, crashes and failing builds.
Specific 97
One situation, audience, tool or format inside the category. Example: Plan a road trip with children.
- Explain a stack trace
Explains an error and its stack trace in plain words, finds the frame that matters, and ranks the likely causes with the next checks to run. Use when an exception or crash is hard to read.
- Debug a production-only bug
Debugs a bug that happens only in production by diffing environment, config, data, traffic, versions and timing, then plans safe instrumentation to confirm the cause. Use for works-on-my-machine bugs.
- Bugfix track
Takes a bug from report to reproduction, root cause, regression test, minimal fix and a verified pull request, stopping for approval between steps. Use for any bug worth fixing properly.
- Debug a failing network request
Diagnoses a failing HTTP request layer by layer (DNS, TLS, proxy, CORS, auth, timeouts, payload) from error output and curl or browser traces, giving the next command at each step.
- Bisect a regression
Finds the commit or input that introduced a regression by writing an automated good/bad check first, then bisecting. Use when something that used to work is broken and the cause is unclear.
- Debug bus communication
Coaches you through failing I2C, SPI, UART or CAN communication one check at a time, from wiring and pull-ups to clock settings, addressing and logic analyser captures.
- Triage a failing CI build
Finds the first real error in a failing CI log, classifies the failure as caused by the change, flaky, environment drift or already broken, and names the next action. Use when a pipeline turns red.
- Fix a WordPress critical error
Recovers a WordPress site from a white screen or "There has been a critical error" by reading the PHP error log and isolating the failing plugin, theme or PHP version change.
- Configure a working IDE debugger
Sets up a debugger configuration (VS Code launch.json, JetBrains run config, attach to Docker, Node or Python) so breakpoints actually hit.
- Debug a mobile app crash
Debugs a mobile app crash from a symbolicated report, reading the crashed thread and frames to find the likely cause, a reproduction and a fix. Use when a crash shows up in the crash reporter.
- Fix an SSH connection error
Fixes SSH failures such as "Permission denied (publickey)", host key verification failed, connection refused or timed out, and wrong key or agent use, by reading the verbose ssh output.
- Diagnose a crash-looping pod
Diagnoses a Kubernetes pod stuck in CrashLoopBackOff, ImagePullBackOff, OOMKilled or Pending from describe output, events and logs, in a fixed order of checks, with the fix for each cause.
- Find the root cause of a bug
Reproduces a bug, tests ranked hypotheses with experiments, and fixes the root cause instead of the symptom. Use when something is broken and the reason is not obvious.
- Fix Docker container networking
Fixes containers that cannot reach each other, the host or the internet, or cannot be reached from the browser, covering localhost confusion, Compose networks, published ports, bind addresses and DNS.
- Fix Python environment mix-ups
Fixes the wrong Python running, pip installing into another environment, externally-managed-environment errors and venv, conda, pyenv or IDE interpreter conflicts so the right Python and packages run.
- Turn a bug report into a minimal reproduction
Turns a vague bug report into a minimal, reliable reproduction, preferably a failing test, and states the exact conditions needed. Use before fixing a reported bug or when triaging issues.
- Fix a CORS error
Fixes a browser CORS error from the exact console message and the preflight and response headers, setting the right server or proxy config with an explicit origin list instead of wildcards.
- Fix failing file uploads
Fixes file uploads that fail with 413, time out, arrive empty or corrupted, or break only on mobile, checking size limits at each hop, multipart parsing, presigned URL CORS and content types.
- Resolve a dependency conflict
Resolves a dependency conflict in npm, pip, Maven or a similar tool by tracing the resolver output to the clashing constraints and choosing the safest versions. Use when an install fails.
- Fix a Flutter layout error
Fixes Flutter RenderFlex overflow, unbounded height or width, and "RenderBox was not laid out" errors by reading the constraint chain from parent to child.
- Fix a mobile build failure
Finds and fixes a failing Xcode, Gradle, CocoaPods, React Native or Flutter build from its log, covering dependencies, signing, toolchain versions and stale caches, with the smallest fix.
- Fix a module import error
Fixes "module not found", "cannot use import statement", circular import and wrong-version import errors in Python, Node.js and TypeScript by tracing how the runtime resolves the module.
- Fix a failing package install
Fixes npm, pip, Poetry or gem install failures caused by native builds, missing wheels, registry auth, proxies, certificates or platform mismatches.
- Fix a misbehaving shell script
Fixes a broken bash script: quoting and word splitting, set -e pitfalls, CRLF line endings, globbing, exit codes and differences between sh and bash.
- Fix Tailwind classes not being applied
Fixes Tailwind classes that have no effect, tracing source detection, dynamically built class names, v3 versus v4 setup, layer order, conflicting classes and specificity in the generated CSS.
- Fix images, CSS or scripts that 404 after deploy
Fixes images, stylesheets, fonts or scripts that load locally but 404 after deploy, from base paths and subfolder hosting, public folder rules, CDN prefixes, SPA fallbacks and filename case.
- Fix an app that cannot connect to its database
Fixes "connection refused", timeouts, authentication failures, SSL errors and "too many connections" when an app cannot reach its database, layer by layer from DNS to credentials.
- Fix hot reload or file watching that stopped working
Fixes a dev server whose hot reload or file watching does not pick up changes, covering watcher limits, Docker mounts, WSL paths, caches and HMR boundaries.
- Fix a null or undefined reference error
Fixes "cannot read properties of undefined", NullPointerException and NoneType errors by tracing where the missing value comes from instead of adding null checks.
- Find why a setting is ignored
Finds why a configuration value or environment variable has no effect by tracing where the program loads settings, which source wins, and what value it actually sees at runtime.
- Fix breakage after a dependency upgrade
Finds why tests or behaviour broke after a dependency update, by diffing lockfiles and changelogs and bisecting packages, then fixes the code or pins safely.
- Fix a date and time bug
Fixes date and time bugs caused by time zones, daylight saving, parsing, formatting or storage, and adds tests for the edge cases that broke it. Use for off-by-one-day and off-by-one-hour bugs.
- Fix a floating-point or rounding bug
Fixes wrong totals, failed equality checks, drifting sums and odd rounding caused by binary floating point, choosing integers, decimals or tolerances, and tests the edge values.
- Fix a JWT validation failure
Fixes JWTs rejected with 401 or "invalid signature" by checking the algorithm, signing key and kid, key rotation, issuer, audience, expiry and clock skew against the decoded token.
- Fix an out of memory crash
Fixes a process dying with Java heap space, JavaScript heap out of memory, Python MemoryError or an OOM kill by measuring what uses memory and fixing load patterns or limits, not just raising them.
- Fix a permission denied error
Fixes "permission denied", EACCES and EPERM errors by finding which user, file mode, owner, mount, container or security policy blocks access, then grants the least access that works.
- Fix physics jitter and tunnelling
Finds why objects jitter, tunnel through walls or explode in a game physics simulation by checking update order, interpolation, timestep, continuous collision and mass ratios, then fixes the cause.
- Fix an infinite redirect loop
Fixes "too many redirects" loops caused by HTTPS behind proxies, auth middleware, trailing-slash rules, CDN settings or locale and canonical-host redirects.
- Fix a data serialization mismatch
Fixes fields that arrive missing, null, renamed or changed between services, clients and storage by comparing the bytes on the wire with what each side's serializer writes and expects.
- Fix an SSL certificate verification error
Fixes CERTIFICATE_VERIFY_FAILED and similar TLS verification errors from missing chains, corporate proxies, self-signed certs or stale CA bundles, without disabling verification.
- Fix a stale cache bug
Finds which cache layer serves old data after an update, from browser and CDN to app, ORM and memoized values, and fixes its invalidation or headers. Use when users still see the old value.
- Fix a text encoding bug
Fixes text encoding bugs such as mojibake, broken emoji, question marks or byte order marks by tracing the bytes through files, databases and APIs to the hop that breaks them. Use for garbled text.
- Solve a debugging case by experiment
Gives a failing program and a bug report, answers the learner's requests for logs, values and experiments consistently, and confirms the root cause only when they reason to it.
- Fix SQLAlchemy session errors
Fixes DetachedInstanceError, lazy loads after the session closes, MissingGreenlet in async code and stale or expired objects by correcting session scope, commit settings and eager loading.
- Decode a minified production stack trace
Maps a minified JavaScript or TypeScript production error back to original lines with source maps, fixes broken source map setups, then explains the real error.
- Diagnose a mobile app freeze
Diagnoses Android ANRs and iOS hangs or watchdog terminations from traces, finding main-thread blocking I/O, locks, binder calls or heavy layout, and fixes each with the right threading tool.
- Find and fix a goroutine leak
Finds leaking or stuck goroutines from pprof goroutine dumps and fixes missing cancellation, blocked channel sends and unclosed resources in Go.
- Fix an Angular change detection error
Fixes ExpressionChangedAfterItHasBeenChecked errors, views that do not update under OnPush, and signal or zone issues in Angular.
- Fix a failing Ansible playbook run
Fixes a failing Ansible run from its output, covering unreachable hosts, privilege escalation, undefined variables and precedence, module errors, handlers and tasks that are not idempotent.
- Fix an AWS AccessDenied error
Fixes AWS AccessDenied and UnauthorizedOperation errors by reading the denied action, principal and resource, then checking identity and resource policies, boundaries, SCPs, KMS and session policies.
Showing 50 of 97. See them all in search
Advanced 4
Expert or deep work that assumes the user can judge expert output. Example: Plan croissant lamination.
- Debug a race condition
Diagnoses intermittent concurrency bugs by mapping shared state and the interleavings that break it, adds targeted instrumentation and proposes a fix. Use for bugs seen only under load.
- Diagnose a hung or frozen process
Diagnoses a process that hangs, freezes or stops making progress by reading thread dumps and stack samples, telling deadlock, livelock, infinite loop and blocked I/O apart, then fixing the cause.
- Debug a native crash
Debugs a native crash or segfault in C, C++ or Rust from core dumps, backtraces and sanitizer output, ranks the likely memory or concurrency causes and names the next command to run.
- Decode a microcontroller hard fault
Decodes an ARM Cortex-M HardFault or similar exception from fault status registers and the stacked frame, locates the faulting instruction via the map file and names the likely cause.
Not: production alerts and outages (incident); flaky tests (testing).