qml-debugging

qml-debugging

Purpose

Use this skill when a PennyLane + PyTorch QML workflow is broken, unstable, or producing misleading results, and the first problem is to diagnose what layer is failing before applying a fix. The goal is to identify the failure class, gather evidence, and hand the issue off to the correct implementation skill instead of guessing or changing multiple layers at once.

Use this skill when

• a QNode fails at runtime
• tensor shapes or measurement outputs do not match the loss path
• gradients are zero, NaN, unstable, or suspiciously tiny
• training does not learn even though code appears to run
• shot-based runs behave inconsistently compared with simulator expectations
• Qiskit-backed execution behaves differently from local PennyLane runs
• you need to decide whether the real issue is model, interface, training, performance, or backend

Do not use this skill when

• the task is already clearly a model redesign; use pennylane-qnn
• the task is already clearly a PyTorch boundary cleanup; use qml-pytorch-interface
• the task is already clearly a training-loop redesign; use qml-pytorch-training
• the task is already clearly a runtime optimization problem on a correct model; use qml-pytorch-performance-patterns
• the task is already clearly a backend extension or backend setup issue; use pennylane-qiskit-backends
• the task is only about fair evaluation across working branches; use qml-cross-framework-benchmarking

Required inputs

Before applying this skill, identify:

• the failing code path or failing stage
• the current device/backend and shot configuration
• input, output, and target shapes
• current loss function and optimizer path
• whether the problem appears in local PennyLane only, Qiskit-backed only, or both
• any concrete error messages, warnings, or suspicious metrics

Core rules

1. Diagnose before changing architecture.
2. Change one layer at a time.
3. Always collect evidence before routing to another skill.
4. Do not confuse non-learning with performance problems.

Decision rules

Shape and output failures

• If the output shape, target shape, or measurement structure is wrong, route next to qml-pytorch-interface or pennylane-qnn depending on whether the failure is at the circuit boundary or the model definition.

Gradient and trainability failures

• If gradients are zero, NaN, or unstable, first confirm that the parameter path is valid and the loss is scalar.
• If the parameter path is correct but the model remains untrainable, treat barren plateau risk or ansatz/cost design as a likely model issue and hand off to pennylane-qnn.
• If the training loop mixes multiple uncontrolled changes, route next to qml-pytorch-training.

Runtime and instability failures

• If code is correct but slow, do not use this skill as the final owner; hand off to qml-pytorch-performance-patterns after correctness is confirmed.
• If shot-based instability or backend-only weirdness appears, hand off to pennylane-qiskit-backends after collecting evidence.

Benchmark escalation

• If two implementations both work but disagree in ways that need controlled comparison, hand off to qml-cross-framework-benchmarking.

Implementation guidance

Recommended debugging sequence

1. Confirm the exact failing stage: model, interface, training, performance, or backend.
2. Record shapes, backend, shot count, and loss expectations.
3. Reduce the failure to the smallest reproducible path.
4. Decide whether the issue is structural, interface-level, training-level, runtime-level, or backend-level.
5. Hand off to one primary owner skill with a concrete diagnosis summary.

Recommended diagnostic output

When using this skill, produce:

• failure class
• evidence collected
• likely root cause
• recommended next owner skill
• what not to change yet

Minimum failure classes

• shape-mismatch
• measurement-mismatch
• gradient-failure
• non-learning-training
• backend-difference
• shot-instability
• performance-misdiagnosis

Pitfalls to avoid

• changing ansatz, optimizer, and backend together while debugging
• treating low accuracy alone as proof of a model bug
• benchmarking a failing implementation instead of diagnosing it
• confusing shot noise with deterministic shape or logic errors
• routing every broken workflow straight to qml-pytorch-training

Verification checklist

• failing stage is identified explicitly
• evidence includes shapes, backend, and error or metric symptoms
• likely root cause is stated
• one primary next-owner skill is selected
• unnecessary secondary changes are deferred

Output standard

When this skill is applied well, the result should turn a vague “it is broken” report into a specific diagnosis with a clear next owner and minimal guesswork.