DeepSeek Workflow

Reasoning-first debugging workflow for DeepSeek

A workflow that makes DeepSeek state a hypothesis and a test before proposing any fix.

LLM Mart · 29 points · 750 415

#agents #coding

## Principle **No fix before a hypothesis, and no hypothesis before a test that would prove it.** This stops the model from pattern-matching a plausible patch onto the wrong cause — which is the characteristic way AI debugging fails, because the patch often *does* make the symptom go away. A symptom that stops appearing is not a bug that stopped existing. Sometimes you've moved it; sometimes you've made it intermittent, which is worse. ## Steps ### 1. Establish the facts — no guessing yet Write down, before any analysis: - The **symptom**, precisely. Not "it's broken" — the exact error, the exact wrong value, the exact observed behaviour. - **Reproduction steps** that work. If you cannot reproduce it, that is the bug you're working on now; everything else is speculation. - **Expected vs actual**, side by side. - **What changed** recently: deploys, dependency bumps, config, data, traffic. - **Scope**: all users or some? All requests or some? Since when? On every environment? That scope question is worth more than it looks. "Only for users created before March" is nearly a diagnosis on its own. ### 2. Generate ranked hypotheses > Give me a ranked list of 3–5 possible root causes. For each: the mechanism, the > evidence that would confirm it, and the evidence that would rule it out. Rank > by likelihood × ease-of-testing. Do not propose fixes yet. Ranking by ease-of-testing as well as likelihood is deliberate: a 30% hypothesis you can eliminate in one minute goes before a 50% hypothesis that takes an hour. Ask for the mechanism, not the category. "A race condition" is not a hypothesis; "two webhook deliveries within the idempotency gap both read `Pending` and both write" is. ### 3. Write a failing test for the top hypothesis > Write the smallest test that fails **if and only if** `{hypothesis}` is the > cause. It should fail for that specific reason — not merely fail. The "if and only if" is what makes this work. A test that fails for several possible reasons tells you nothing when it goes red. ### 4. Run it - **Fails as predicted** → you've located the cause. Go to step 5. - **Passes** → cross the hypothesis off the list and drop to the next one. This is progress, not a setback: you've eliminated a branch, and you have a test you didn't have before. - **Fails for a different reason** → stop and read it. You've found something else, and it may be the actual bug. ### 5. Fix, minimally Change only what the confirmed cause requires. Re-run the new test — now green — and the full suite — still green. Resist the urge to clean up nearby code in the same commit; a fix that's readable in isolation is one you can revert at 3am. ### 6. Write the root cause in one sentence For the commit message, for the PR, and for yourself. Then ask the question that pays for the whole exercise: > What else in this codebase has the same shape of bug? Most bugs are instances of a class. Fixing one and finding four more is a good afternoon. ## Prompts that keep it honest - *"Before proposing a fix, tell me which hypothesis it addresses and how the test proves it."* - *"What would make this fix wrong? What did we not test?"* - *"You just proposed a fix without a confirmed hypothesis. Go back to step 2."* - *"Is this the cause, or a thing that also happens to be true?"* ## Anti-patterns to refuse - **Shotgun edits** — "try changing these five things". If it works you don't know why, which means you can't tell whether it'll come back. - **Fixing the symptom** — swallowing the exception, adding a retry, adding a null check where the null shouldn't exist. Ask: *why was it null?* - **Fixing the test** to match the broken behaviour. - **Adding logging and calling it done.** Logging is how you get evidence for the next iteration, not a resolution. - **Accepting "it's a race condition" as a diagnosis.** Which two operations, in which order, sharing what state? ## When you cannot reproduce That's the whole task, and the workflow still applies — the hypotheses are now about *why* it doesn't reproduce: - Environment difference (config, versions, timezone, locale, hardware) - Data difference — the row that only exists in production - Concurrency or timing that your test runs too fast to hit - Scale — it only appears past some volume - State accumulated over time; a fresh test database has none Add observability targeted at *distinguishing between those hypotheses*, ship it, wait. Untargeted logging just produces more haystack. ## Why reasoning models suit this A model that thinks before answering is markedly better at step 2 — enumerating causes and reasoning about which evidence discriminates between them — and that is the step that determines whether the whole process converges. Give it the facts from step 1 in full; the quality of the hypothesis list tracks the quality of the facts you fed it almost exactly.

Principle

No fix before a hypothesis, and no hypothesis before a test that would prove it. This stops the model from pattern-matching a plausible patch onto the wrong cause — which is the characteristic way AI debugging fails, because the patch often does make the symptom go away.

A symptom that stops appearing is not a bug that stopped existing. Sometimes you've moved it; sometimes you've made it intermittent, which is worse.

Steps

1. Establish the facts — no guessing yet

Write down, before any analysis:

The symptom, precisely. Not "it's broken" — the exact error, the exact wrong value, the exact observed behaviour.
Reproduction steps that work. If you cannot reproduce it, that is the bug you're working on now; everything else is speculation.
Expected vs actual, side by side.
What changed recently: deploys, dependency bumps, config, data, traffic.
Scope: all users or some? All requests or some? Since when? On every environment?

That scope question is worth more than it looks. "Only for users created before March" is nearly a diagnosis on its own.

2. Generate ranked hypotheses

Give me a ranked list of 3–5 possible root causes. For each: the mechanism, the evidence that would confirm it, and the evidence that would rule it out. Rank by likelihood × ease-of-testing. Do not propose fixes yet.

Ranking by ease-of-testing as well as likelihood is deliberate: a 30% hypothesis you can eliminate in one minute goes before a 50% hypothesis that takes an hour.

Ask for the mechanism, not the category. "A race condition" is not a hypothesis; "two webhook deliveries within the idempotency gap both read Pending and both write" is.

3. Write a failing test for the top hypothesis

Write the smallest test that fails if and only if {hypothesis} is the cause. It should fail for that specific reason — not merely fail.

The "if and only if" is what makes this work. A test that fails for several possible reasons tells you nothing when it goes red.

4. Run it

Fails as predicted → you've located the cause. Go to step 5.
Passes → cross the hypothesis off the list and drop to the next one. This is progress, not a setback: you've eliminated a branch, and you have a test you didn't have before.
Fails for a different reason → stop and read it. You've found something else, and it may be the actual bug.

5. Fix, minimally

Change only what the confirmed cause requires. Re-run the new test — now green — and the full suite — still green. Resist the urge to clean up nearby code in the same commit; a fix that's readable in isolation is one you can revert at 3am.

6. Write the root cause in one sentence

For the commit message, for the PR, and for yourself. Then ask the question that pays for the whole exercise:

What else in this codebase has the same shape of bug?

Most bugs are instances of a class. Fixing one and finding four more is a good afternoon.

Prompts that keep it honest

"Before proposing a fix, tell me which hypothesis it addresses and how the test proves it."
"What would make this fix wrong? What did we not test?"
"You just proposed a fix without a confirmed hypothesis. Go back to step 2."
"Is this the cause, or a thing that also happens to be true?"

Anti-patterns to refuse

Shotgun edits — "try changing these five things". If it works you don't know why, which means you can't tell whether it'll come back.
Fixing the symptom — swallowing the exception, adding a retry, adding a null check where the null shouldn't exist. Ask: why was it null?
Fixing the test to match the broken behaviour.
Adding logging and calling it done. Logging is how you get evidence for the next iteration, not a resolution.
Accepting "it's a race condition" as a diagnosis. Which two operations, in which order, sharing what state?

When you cannot reproduce

That's the whole task, and the workflow still applies — the hypotheses are now about why it doesn't reproduce:

Environment difference (config, versions, timezone, locale, hardware)
Data difference — the row that only exists in production
Concurrency or timing that your test runs too fast to hit
Scale — it only appears past some volume
State accumulated over time; a fresh test database has none

Add observability targeted at distinguishing between those hypotheses, ship it, wait. Untargeted logging just produces more haystack.

Why reasoning models suit this

A model that thinks before answering is markedly better at step 2 — enumerating causes and reasoning about which evidence discriminates between them — and that is the step that determines whether the whole process converges. Give it the facts from step 1 in full; the quality of the hypothesis list tracks the quality of the facts you fed it almost exactly.