Debug Issue

Reproduce first, theorise second. A hypothesis formed before a failing command exists is a guess dressed as a plan.

Phase 0: Contention and real state

Before any code hypothesis: is another process, agent, worktree, or the user's other tool touching the same branch, database, port, session, or shared credential/token store? (git worktree list, lsof -i :<port>, ask "is another tool on this?"). Rule it out first — flaky behaviour under contention looks exactly like a code bug, and two clients refreshing the same rotating token invalidate each other.

• When you have read access, look at the real failing record, user, or job state (read-only) before hypothesising — it often names the cause outright.
• Never blind-retry a side-effecting call (POST, send, payment, migration) that failed part-way: read the remote state first, because the first attempt may have half-succeeded.

Phase 1: Build a red-capable loop

Build one command — a test, curl, CLI + fixture, headless script, replayed trace, or throwaway harness — that you have already run once and that goes red on this exact symptom. It must:

• assert the user's symptom, not "runs without erroring";
• be deterministic, seconds-fast, and runnable by you without the user;
• print only redacted output: secrets become <REDACTED>, credentials stay in env vars, captured artifacts (HAR, request dumps) are quoted only on the lines that carry the signal.