Technical

Track every debugging lead on one map

Give each possible cause its own branch, record what you find under it, and see which leads are ruled out and which are still open.

See it in action

Users report intermittent 502 errors on our checkout API. Help me debug this
Intermittent 502s typically point to upstream timeout, resource exhaustion, or deployment-related instability. Start by correlating the error timestamps with deploy events, load spikes, and dependent service health checks.
How do I distinguish between upstream timeout and connection pool exhaustion?
Check your load balancer logs for upstream_response_time vs upstream_connect_time. If connect_time is high but response_time is low, the pool is likely exhausted. If response_time is high, the upstream service itself is slow. Also check for connection reuse metrics — a leak will show monotonically increasing active connections.

How it works

Paste the symptom and the model proposes possible causes. Each cause gets its own branch, and every question under it keeps the symptom and that cause in context.

  1. Describe the symptom. Paste the error message, stack trace or user report. Ask for likely causes, such as infrastructure, application logic, race conditions or external dependencies.

  2. Branch into checks for each cause. Under “connection pool exhaustion”, ask what to check: pool metrics, timeout settings, how your ORM opens and closes connections. Start with the check that is quickest to run.

  3. Record what you find. Add a note node under the branch with the result, such as “pool size 20, peak active connections 19”. Ask your next question under the note, and the model takes the result into account.

  4. Close out dead ends. Collapse or delete the branches the evidence rules out. The branch that is left, with its notes, is your record for the postmortem.

Why a map instead of linear notes

Notes like “tried X, didn’t work, tried Y” lose their structure. When you return to a lead you dropped an hour ago, you reread everything to remember why you dropped it. On a map, each lead has its own branch with its own results.

A symptom in a distributed system can come from any of several services or infrastructure layers. Give each one a branch so separate lines of investigation stay apart.

Example

Say your integration tests fail now and then in CI. The map branches into flaky tests, environment drift, resource contention and race conditions. Under flaky tests you check test isolation and shared state, and under environment drift you check Docker image versions and dependency caching. The shared-state branch and the resource-contention branch both lead to one Redis instance used for test isolation and for caching. That explains why failures follow parallel test runs and not code changes.

Ready to try debugging?