reproducing-magic-state-cultivation-workflows

name	reproducing-magic-state-cultivation-workflows
description	Guides staged reproduction of magic-state-cultivation workflows from Strilanc's reference repo, including circuit generation, long-run statistics collection, and plot regeneration without collapsing those stages together.
version	0.1.0
author	QEC Research Skills
license	MIT
tags	["QEC","Magic States","Cultivation","Stim","Sinter"]
dependencies	["qec-research","building-stim-circuits"]

Reproducing Magic-State-Cultivation Workflows

What This Skill Is For

Use this skill when the task is to reproduce or adapt the staged workflow behind magic-state-cultivation:

• generate cultivation circuits,
• inspect or customize a paper circuit family,
• collect statistics in a controlled long-running workflow,
• regenerate plots from previously collected data.

When To Use It Versus Alternatives

Use this skill when the user wants the repo structure and execution order used in Craig Gidney's cultivation codebase.

Use building-stim-circuits when the task is only low-level circuit authoring.

Do not use this skill for generic magic-state distillation summaries with no implementation intent.

Required Artifacts And Assumptions

Expected inputs:

• target cultivation stage or circuit family,
• noise strength and gateset assumptions,
• whether the goal is circuit generation, stats recollection, or figure regeneration.

Expected outputs:

• a stage-aware reproduction plan,
• custom circuit-generation arguments when needed,
• explicit compute and time-risk notes for data collection,
• a list of reusable artifacts such as circuits, stats tables, or plots.

Assumptions to make explicit:

• whether the user needs a paper-faithful run or a small local smoke run,
• whether debug HTML output is needed,
• whether recollection is meant to reuse or replace existing stats,
• whether large compute is available.

Standard Workflow Checklist

1. Read references/repo-structure-and-workflow.md.
2. Decide which stage is actually needed: step1_make_circuits, step2_collect, step3_plot, or custom tools/make_circuits.
3. Start from a tiny custom circuit before planning full paper-scale recollection.
4. Keep circuit generation, statistics collection, and plotting as separate artifacts.
5. If using custom circuit generation, write down circuit_type, basis, gateset, d1, d2, r1, and r2 explicitly.
6. Treat paper-scale recollection as a batch workflow, not an interactive default.

Validation Loop

Before closing work:

1. confirm the selected stage matches the user's actual need,
2. confirm any large compute requirement is stated plainly,
3. confirm generated circuits can be inspected before long data collection begins,
4. confirm plots are tied to named input stats instead of being treated as standalone evidence.

Common Issues And Fixes

Stage collapse

Problem: circuit generation, data collection, and plotting are described as one opaque command.

Fix: split the workflow into the same staged pipeline used upstream.

Paper-scale recollection by default

Problem: a local run is planned as if full statistics recollection were cheap.

Fix: use a small custom circuit or reduced shot/error targets first.

Hidden parameter drift

Problem: custom generation omits the exact cultivation parameters.

Fix: record all generation arguments before running or rewriting anything.

References

• references/api.md
• references/examples.md
• references/repo-structure-and-workflow.md
• ../../01-circuits/building-stim-circuits/SKILL.md
• ../../docs/TOOLKIT_REGISTRY.md