Investigate a problem
=====================

This entry point helps assign a problem to the correct layer before narrowing
it down reproducibly.

1. Establish a safe state
-------------------------

If the RF level is unexpected, amplifier protection is missing, or RF-off
cannot be reached, stop the measurement in a controlled manner. Investigate
the cause only after switching RF off, and do not disable a protection
feature for diagnosis.

2. Classify the symptom
-----------------------

The :doc:`troubleshooting guide <../help/troubleshooting>` directly covers:

* missing DOT, INI, and DAT files;
* invalid conditions and ambiguous signal paths;
* VISA, GPIB, and Prologix problems;
* measurements that appear to block;
* autosave and resume;
* Qt and Sphinx failures in CI.

3. Check configuration or code
------------------------------

Use :doc:`configuration validation <../configuration/validation>` when the
failure occurs before an actual measurement value is acquired. The
:doc:`testing guide <../framework/testing>` helps with failures in
algorithms, instrument contracts, virtual workflows, safety, resume, or UI
threads.

4. Describe the failure reproducibly
------------------------------------

Record versions, operating system, VISA backend, script, ``conf.py``, last
log lines, and the affected measurement range. Also state whether the
corresponding virtual run succeeds. Do not disclose credentials or
confidential instrument addresses.

Exceptions and public methods are listed in the
:doc:`API reference <../../api/index>`.