name: laboneq-workflow-maintainer description: Maintain and debug existing LabOne Q experiment/analysis workflows in this repository. Use for bug fixes, review follow-ups, and minor behavior changes under qubit_experiment/, experiments/, analysis/, and qpu_types/.

LabOne Q Workflow Maintainer

Scope

Use for maintenance work on existing modules:

• bug fixes from PR/review feedback
• workflow Reference and OptionBuilder failures
• acquisition/update contract drift
• small behavior extensions in existing experiment/analysis modules

Do not use for brand-new module creation or major redesigns. For those, use skills/module-builder/SKILL.md.

Triage Gate (before code edits)

1. Identify the failing path and exact file/function.
2. Classify root cause:

• workflow Reference misuse
• option builder typing/assignment issue
• acquisition/averaging contract mismatch
• update_qpu/parameter update path mismatch
• task-boundary violation (workflow.log/comment/save_artifact)

1. List paired modules that must stay in sync (experiments/* and analysis/*).

Hard Rules

• Prefer canonical package edits under qubit_experiment/*; keep top-level compatibility modules import-compatible.
• Keep experiment and analysis behavior aligned when changing interfaces or outputs.
• In @workflow.workflow bodies, use workflow control flow (workflow.if_, workflow.for_), not Python if/for/while.
• Treat workflow outputs as Reference; avoid Python truthiness and container methods on unresolved values.
• Treat optional workflow inputs and workflow-parameter objects as potentially unresolved during graph construction; do not run int(...), bool(...), isinstance(...), x is None, or attribute-based branching on them in the workflow body. Resolve them in helper tasks first.
• Set options with call style only (opt.field(value)), never assignment (opt.field = value).
• Do not assemble notebook-facing nested dict/list payloads inline in workflow returns when nested fields come from tasks or sub-workflows. Keep returns top-level, or assemble nested bundles in helper tasks or plain Python wrappers.
• When public maintenance code accepts both plain option objects and OptionBuilders, normalize them explicitly before reading fields.
• Call workflow.comment(...), workflow.log(...), and workflow.save_artifact(...) only inside @workflow.task.
• Enforce acquisition/averaging constraints in create_experiment(...) with explicit ValueError.
• Persist updates only via analysis_results.output["new_parameter_values"] + update_qpu(...).
• Do not use deprecated update_qubits in new maintenance code.
• Every bug fix should include a regression test under tests/ unless explicitly blocked.

Maintenance Workflow

1. Reproduce failure (or trace it from logs/review notes) and isolate the smallest failing path.
2. Implement a minimal fix in canonical modules; touch legacy wrappers only when required for compatibility.
3. Update paired experiment/analysis modules if interfaces or outputs changed.
4. Add or adjust regression tests targeting the failure mode. For notebook-facing payloads, include a recursive assertion that no nested value is a laboneq.workflow.reference.Reference.
5. Run fast checks:

ruff check .
pytest -q

1. Report root cause, changed contract (if any), and validation evidence.

Quick PR Review Checklist

• Any workflow Reference consumed via Python control flow?
• Any workflow input or options object being cast/inspected directly in the workflow body?
• Any branch-local value read after a conditional chain?
• Any OptionBuilder field written by assignment?
• Any nested workflow return payload likely to leak Reference values into notebook output?
• Any analysis-derived output used when do_analysis=False?
• Any persistent update path missing new_parameter_values keys?
• Did the fix include a test that fails before and passes after?

References

• ../module-builder/SKILL.md (shared LabOne Q workflow contracts)