Skip to content

DevNullLtd/Yuzu / .codex/skills/diagnose

diagnose

Unverified

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

  1. Reproduce: confirm the loop shows the same symptom the user reported.
  2. Minimize: reduce the input, fixture, test, or command until the signal is sharp.
  3. Hypothesize: list 3-5 ranked falsifiable hypotheses and the prediction each makes.
  4. Instrument: probe one hypothesis at a time. Use debugger/REPL first, targeted logs second.
  5. Fix: add the regression test at the correct seam before the fix when possible.
  6. Verify: run the original loop, the regression test, and the relevant targeted suite.
  7. 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.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall