simulating-cc-code-surgery-protocols

name	simulating-cc-code-surgery-protocols
description	Guides color-code and related surgery-protocol simulation using local surgery implementations, with explicit matrix, circuit, detector-model, and decoder validation stages.
version	0.1.0
author	QEC Research Skills
license	MIT
tags	["QEC","Surgery","Color Code","Stim","BP-OSD"]
dependencies	["qec-research","building-stim-circuits","decoding-with-ldpc"]

Simulating CC Code Surgery Protocols

What This Skill Is For

Use this skill when the task is to build, inspect, or validate a surgery protocol similar to the local color-code surgery stack:

• construct connection-code matrices,
• generate exact X- or Z-type surgery circuits,
• extract detector error models,
• run a decoded smoke test before scaling,
• stage validation carefully before any broader sweep workflow.

When To Use It Versus Alternatives

Use this skill when the protocol begins from matrix-level surgery design and ends in a decoded Stim workflow.

Use building-stim-circuits when the circuit structure is already fixed.

Use decoding-with-ldpc when the detector-model artifacts already exist and the task is decoder-only.

Required Artifacts And Assumptions

Expected inputs:

• surgery type (X or Z),
• code family or code name,
• connection-code data such as H_a' and H_b',
• noise model and round counts,
• whether the task is semantic verification, DEM extraction, or decoded performance.

Expected outputs:

• a matrix-layer plan,
• a circuit-generation plan,
• DEM and decoder handoff notes,
• a smoke-test plan before any sweep.

Assumptions to make explicit:

• whether the task follows the cc_surgery matrix/circuit conventions,
• whether BP-OSD is the intended first decoder,
• whether the workflow needs only the cc_surgery matrix/circuit/decoder path or a more general future adapter.

Standard Workflow Checklist

1. Read references/local-repo-workflow.md and decide whether the request is best matched by the cc_surgery lane
2. Start at the matrix layer: pick example data or construct new H_a' and H_b'.
3. Check commutation and measured-observable counts before generating any noisy circuit.
4. Build the exact surgery circuit with explicit noise and round counts.
5. Compile the detector error model and sample a decoded smoke test before any sweep.
6. Only after the smoke path works, move to sweep.py, plot_threshold.py, or broader sinter-style batch workflows.

Validation Loop

Before closing work:

1. confirm matrix commutation or analogous structural checks passed,
2. confirm the exact circuit builder and noise model are named explicitly,
3. confirm DEM extraction happened before decoder benchmarking claims,
4. confirm the first run is a smoke test, not a threshold claim.

Common Issues And Fixes

Starting from sweeps instead of invariants

Problem: the workflow jumps directly to large runs.

Fix: run semantic and matrix checks first.

Overfitting to one private implementation

Problem: the workflow depends on details of a non-public local implementation instead of portable principles.

Fix: keep only the reusable ideas: staged validation, explicit measurement scheduling, logical deformation bookkeeping, DEM bookkeeping, and batch simulation design.

Decoder-first reasoning

Problem: BP-OSD configuration is discussed before the circuit and DEM are stable.

Fix: freeze the matrix and circuit layers first, then decode.

References

• references/api.md
• references/examples.md
• references/local-repo-workflow.md
• ../../01-circuits/building-stim-circuits/SKILL.md
• ../../02-decoders/decoding-with-ldpc/SKILL.md
• ../../docs/TOOLKIT_REGISTRY.md