| name | diagnose |
| description | Diagnose Yuzu bugs and performance regressions with a disciplined reproduce-minimize-hypothesize-instrument-fix-regression-test loop. Use when the user says `/diagnose`, "debug this", reports a failure, flake, broken behavior, or performance regression. |
Diagnose
Build a feedback loop before guessing. Read CONTEXT.md and relevant ADRs so hypotheses use Yuzu's domain vocabulary.
Loop First
Create the fastest deterministic signal that reproduces the user-visible failure:
- focused unit or integration test
scripts/start-UAT.sh plus REST/gRPC/CLI probe- gateway EUnit/CT/Dialyzer command
- replayed log, request, proto payload, or DB fixture
- reduced harness around a store, handler, plugin, or gateway module
- repeated stress loop for flakes
- perf measurement before changing code
If no loop is possible, stop and ask for the missing artifact or environment. Do not proceed on vibes.
Phases
- Reproduce: confirm the loop shows the same symptom the user reported.
- Minimize: reduce the input, fixture, test, or command until the signal is sharp.
- Hypothesize: list 3-5 ranked falsifiable hypotheses and the prediction each makes.
- Instrument: probe one hypothesis at a time. Use debugger/REPL first, targeted logs second.
- Fix: add the regression test at the correct seam before the fix when possible.
- Verify: run the original loop, the regression test, and the relevant targeted suite.
- Cleanup: remove temporary probes and
[DEBUG-...] logs; delete throwaway harnesses unless intentionally kept under a debug path.
Yuzu Checks
- For Erlang failures, source
scripts/ensure-erlang.sh; remember rebar3 eunit --module is not isolation.
- For build/test selection, invoke
$yuzu-build.
- For Meson/proto/plugin/Windows boundaries, invoke the matching Yuzu skill.
- For performance, use measurement scripts such as
scripts/test/perf-gate.sh or a narrow harness before and after. Perf gates are measure-only unless the specific test enforces a threshold.
Final Report
State the reproduced symptom, the hypothesis that won, the fix, the regression test, exact validation commands, and any architectural gap that prevented a clean regression test.
