Diagnose from the earliest wrong stage

A Flow program passes through parse, type check, C emission, C compile, link, and run. Find the first stage that went wrong and fix it there. Fixing a symptom three stages downstream produces a change that looks right and is not.

Stage 0: is it the host?

flowc emit failed (Stage-A subset?). Use FLOW_HOST=python for full language.
stage_a_driver_flow: parse failed

This is the most common Flow failure and it is not a bug in the program. The default flowc host covers a subset. Anything with println, a flow block, an effect, generics, or modules needs:

FLOW_HOST=python flow run program.flow

Try this before reading a single line of the source.

Stage 1: parse and type check

FLOW_HOST=python flow compile program.flow --strict
FLOW_HOST=python flow explain program.flow

--strict turns type warnings into failures. explain prints the compilation plan for every declarative construct: what was considered, what was chosen, and what each rejected candidate failed on. Use it when a construct compiled but lowered to something you did not expect.

Stage 2: the generated C

FLOW_HOST=python flow compile program.flow
cat "$FLOW_HOME/build/program.c"

Read the C as a diagnostic instrument. It tells you what a construct actually became. Never edit it. It is regenerated on every build, so a fix there disappears and, worse, appears to work first.

If the C is wrong, the fix belongs in the generator, in compiler/src/ or src/flow/.

Stage 3: the C compiler and linker

A parser-accepted extern is not proof that a symbol links. Run it.

Stage 4: runtime

FLOW_HOST=python flow run program.flow --sanitize=ub,asan
FLOW_HOST=python flow debug program.flow --break main

Sanitizers catch out-of-bounds access, use after free, integer overflow, and alignment faults. Reach for them the moment a crash is not obviously a logic error, and for anything with ptr<T> or manual memory.

flow debug builds with debug info and can launch LLDB or GDB. --no-launch builds without launching.

Stage 5: wrong numbers

The program ran and the answer is wrong. This is a model problem far more often than a compiler problem.

1. Halve dt and rerun. If the answer moves, the step size was the problem.
2. Check a conserved quantity. If energy drifts, the integration is wrong.
3. Compare against a closed-form answer for a simplified case.
4. Print the state at the first few steps and compare against a hand calculation.
5. Only then suspect the compiler, and prove it with a minimal reproduction.

Silent failures

Minimal reproduction

Cut the program down until removing one more line makes the failure vanish. Report that file, the exact command with environment variables, and the real output. A ten-line reproduction is worth more than a paragraph of description.

Report

State which stage failed, what the evidence was, what you changed, and the command that now passes. If you fixed a symptom rather than a cause, say so plainly.