references/debugging-playbook.md

# Systematic SQL debugging

Start with the smallest observation: wrong total, missing row, duplicate key, invalid cast, parser error, unexpectedly slow query or permission error. Reproduce on a minimal example only when a real test runtime exists.

For wrong totals, inspect source measures before each join, then count keys at each CTE. For missing rows, inspect join type and WHERE predicate placement. For time drift, compare UTC instants versus local grouping. For dialect errors, isolate the expression and consult target reference. For permissions, inspect grant scope instead of recommending broad access.

## Output discipline
Separate **observed evidence** from **hypotheses**, show the few most useful probes first, and explain how each result would change the diagnosis. Present minimal code changes, then regressions tests. Do not quote imagined database output as if observed.