building-stim-circuits

name	building-stim-circuits
description	Provides guidance for constructing, validating, and exporting stabilizer QEC circuits with Stim when studying memory experiments, syndrome extraction, or detector-model workflows.
version	0.1.0
author	QEC Research Skills
license	MIT
tags	["QEC","Stim","Circuits","Stabilizer Codes"]
dependencies	["qec-research"]

Building Stim Circuits

What This Skill Is For

Use this skill when a task needs a concrete stabilizer-circuit workflow:

• build or inspect a Stim circuit,
• compile a detector model,
• sample trajectories,
• package circuit outputs into repo artifacts.

When To Use It Versus Alternatives

Use this skill when the workload is naturally low-level and Stim is the right primary backend.

Prefer future surface-sim workflows when the task is centered on structured logical-gate sequences, layout-aware surface-code operations, or user-facing logical-circuit construction rather than low-level circuit inspection.

Do not treat Stim .dem files as the universal internal representation. Use them as one artifact family among several.

Required Artifacts And Assumptions

Expected inputs:

• a code or workload description,
• an explicit noise model or a statement that noiseless construction is intended,
• the target artifact family to export or inspect.

Expected outputs:

• CircuitBundle,
• optional DetectorModelBundle,
• optional TrajectoryBundle.

Assumptions to make explicit:

• which code family is being studied,
• whether the requested noise model is code-capacity-like, phenomenological, or circuit-level,
• whether graphlike detector models are required,
• whether observables and detector indexing need stable naming,
• whether downstream decoder compatibility matters immediately.

Standard Workflow Checklist

1. Read research-state.yaml and confirm the current workload and backend assumptions.
2. Check servers/contracts/qec_circuits_mcp.yaml for the intended tool surface.
3. Identify whether the task is circuit construction, detector-model compilation, sampling, or inspection.
4. Classify the requested noise model before choosing parameters: code-capacity-approx, phenomenological, or circuit-level.
5. Keep the output in the shared artifact families instead of returning large inline payloads.
6. Record any backend-specific assumption that would affect later decoding or benchmarking.

Validation Loop

Before closing work:

1. confirm the circuit spec is explicit enough to reproduce,
2. confirm the detector-model or trajectory export path is recorded,
3. confirm the chosen noise profile is recorded and matches the actual Stim parameters used,
4. confirm backend-specific assumptions are written into project state or log,
5. confirm the result is described as a Stim artifact, not a repo-wide canonical IR.

Common Issues And Fixes

Implicit decoder assumptions

Problem: a circuit is generated as if any decoder can consume its derived detector model.

Fix: record whether graphlike structure, observable ordering, or trajectory-level data is required by the downstream decoder lane.

Wrong noise-model abstraction

Problem: a request for code-capacity, phenomenological, or circuit-level noise is translated into whichever Stim knobs happen to be convenient.

Fix: map the requested study type onto an explicit profile first. Use references/noise-models.md and record when the current generated-circuit lane is only an approximation, especially for strict code-capacity studies or variable-latency idling.

Tool-specific leakage

Problem: the workflow starts describing the project in terms of Stim file formats only.

Fix: map the output back to shared artifact families like CircuitBundle and DetectorModelBundle.

Validation drift

Problem: a circuit exists on disk, but there is no record of what was checked.

Fix: update research-log.md or registry metadata with the validation status and remaining caveats.

References

• references/api.md
• references/examples.md
• references/noise-models.md
• docs/ARTIFACT_MODEL.md
• docs/TOOLKIT_REGISTRY.md
• servers/contracts/qec_circuits_mcp.yaml