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)

3. 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.
• Set options with call style only (opt.field(value)), never assignment
  (opt.field = value).
• 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.
5. Run fast checks:

ruff check .
pytest -q

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

Quick PR Review Checklist

• Any workflow Reference consumed via Python control flow?
• Any branch-local value read after a conditional chain?
• Any OptionBuilder field written by assignment?
• 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)