Debug Flow

Overview

Static reading of code often produces confident wrong guesses. A broken flow — a UI journey, an API request, a CLI command, a background job — needs a temporary, correlated trail across every layer it crosses: the human reproduces once, the agent reads the sink (or a paste), and the first divergence names the real fault.

Core discipline:

No fix until the trail shows the first divergence — then densify only there, fix the cause, and delete every debug line you added.

This skill is for this bug's trail. It is not permanent production observability.

When to Use

• A bug needs reproduction (“button does nothing”, “wrong data after save”, “job never runs”, “CLI exits wrong”)
• The flow fails at a specific step and it is unclear which layer is wrong — client, API, service, worker, DB, script, or the wiring between them
• The agent is guessing from code alone and needs runtime evidence
• The user will reproduce locally (“add logs and I’ll repro”, “trace this flow”, “why is this request wrong”)