The /debug-flow Skill

What it does

debug-flow turns a broken flow — a UI journey, an API request, a CLI command, a background job — into a temporary, correlated trail across every layer it crosses, then deletes every debug line once the cause is fixed.

Static reading of code produces confident wrong guesses. This skill expects a human reproduction, sparse boundary logs keyed by one debugRunId, and a walk of the trail to the first divergence.

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

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

When to reach for it

• Button does nothing, wrong data after save, job never runs, CLI exits wrong
• Unclear which layer is wrong — client, API, service, worker, DB, script, or the wiring
• The agent is guessing from code and needs runtime evidence
• You’ll reproduce locally (“add logs and I’ll repro”, “trace this flow”)

Do not use for:

Situation	Better fit
Permanent production logging/metrics/tracing	instrumenting-for-observability
Static-only review with no planned repro	Ordinary code review
Browser automation / agent-driven browser loops	Out of scope for this skill
Perf profiling, visual polish, flaky E2E authorship	Other tooling

Prerequisites

A human who can reproduce locally — browser, terminal, curl, or a test run. Automation MCPs are not required and are out of scope. The skill uses whatever logger, console, or print facility the repo already has.

How it works

1. Capture the symptom — Expected vs actual, exact repro, environment, one concrete input. Don’t instrument a vague “it’s broken.”
2. Map the flow — Sketch entry → handlers → boundary calls → core logic → output with unknowns. No code changes yet.
3. Instrument sparsely — One debugRunId; boundary logs only (entry, .request, .entry, .exit / .error, .response, apply) with a shared log contract. Name layers after the code: ui, client, api, service, worker, db, cli.
4. Reproduce once — Tell the human exactly what to do and what to copy. Wait for evidence.
5. Find the first divergence — Last expected line vs first wrong/missing line.
6. Densify only there — Extra logs at the fault boundary, not everywhere.
7. Fix the cause, then delete the trail — Temporary means temporary.

What you get

A short-lived debug trail that names the real fault, a targeted fix, and a clean working tree with debug instrumentation removed.

Log contracts and densify rules live in the source skill.

Common questions

Why not fix from reading the code?
Because the first wrong guess looks obvious in a diff and wastes a cycle. The trail is cheaper than two wrong fixes.

Isn’t this just observability?
No. Production instrumentation stays. This trail is deleted when the bug is understood.

What if I can’t paste logs?
Prefer sinks the agent can read locally. Otherwise paste the matching lines plus the failing call’s status for that debugRunId.

Wasn’t this debugging-ui-flows?
Yes. It was renamed to debug-flow and generalized beyond UI→API journeys. Install by the new name.

It’s working if

• Instrumentation waits until the symptom and flow map are clear
• First-pass logs are sparse boundary markers, not every function
• The root cause is named from the first divergence, not a hunch
• Extra logs only appear around that divergence
• Every debug line is gone after the fix

Where it fits

Use when a flow is broken now. When you’re about to ship a change and want it diagnosable later, use instrumenting-for-observability. If the session ends mid-diagnosis, capture state with handing-off-work.