decoding-with-tesseract-decoder

name	decoding-with-tesseract-decoder
description	Guides search-based decoder planning with tesseract-decoder for small or medium QEC studies, keeping its baseline value separate from scalable matching or hypergraph lanes.
version	0.1.0
author	QEC Research Skills
license	MIT
tags	["QEC","Tesseract","Search","Decoders"]
dependencies	["qec-research","building-stim-circuits","choosing-qec-decoders"]

Decoding With tesseract-decoder

What This Skill Is For

Use this skill when the user wants a search-based decoder lane:

• add a stronger small-instance comparison baseline,
• study a decoder that works directly from a Stim circuit or DEM,
• reason about beam-search and A*-style decoder tradeoffs,
• preserve the fact that throughput is not the only axis that matters.

When To Use It Versus Alternatives

Use this skill when the workload is:

• small or medium enough that search is scientifically plausible,
• better served by a high-quality comparison baseline than by maximum throughput,
• representable as a Stim circuit or detector model.

Prefer decoding-with-pymatching or decoding-with-fusion-blossom when the task is really about matching-graph throughput or exact-MWPM comparison.

Prefer choosing-qec-decoders when the main question is whether the workload should be search-based, hypergraph-aware, or toolkit-native at all.

Do not present tesseract-decoder as the next default repo lane. Its value is targeted comparison, not broad baseline replacement.

Current Repo Boundary

This repo does not yet integrate tesseract-decoder.

The correct current use is:

• route search-based comparison requests honestly,
• reuse the upstream Python and sinter surfaces in planning docs,
• keep environment compatibility explicit before promising local execution.

Required Artifacts And Assumptions

Expected future repo inputs:

• DetectorModelBundle,
• TrajectoryBundle,
• possibly a CircuitBundle when the adapter chooses to keep direct Stim-circuit workflows visible.

Assumptions to make explicit:

• the problem size is appropriate for a search-based baseline,
• the scientific goal values search quality more than large-scale throughput,
• environment compatibility has been checked instead of assumed.

Standard Workflow Checklist

1. Read research-state.yaml for the current decoder-roadmap assumptions.
2. Check servers/resources/decoder_capability_matrix.yaml and servers/resources/decoder_workload_templates.yaml.
3. Record why a search-based baseline is worth the extra complexity.
4. Record whether the study starts from a Stim circuit, a DEM, or a future sinter task set.
5. Keep the summary explicit that the repo lane is still planned.

Validation Loop

Before closing work:

1. confirm the task is really small/medium or comparison-oriented,
2. confirm the answer does not market tesseract-decoder as a throughput lane,
3. confirm environment constraints are mentioned,
4. confirm the summary says "planned search-based lane" instead of implying integrated repo support.

Common Issues And Fixes

Treating search as a scalable default

Problem: tesseract-decoder is recommended for large threshold sweeps where the main need is fast repeated decoding.

Fix: move back toward matching-style lanes or a future benchmark executor.

Hiding the environment story

Problem: the workflow is described as immediately runnable even though the repo has not validated the package in its current baseline.

Fix: say explicitly that this is a documentation-first lane until packaging and smoke tests exist here.

Confusing baseline strength with universality

Problem: a strong search-based comparison on one code family is described as a general decoder result.

Fix: keep the task shape visible: code family, size regime, and scientific purpose of the comparison baseline.

References

• references/api.md
• references/examples.md
• docs/TOOLKIT_REGISTRY.md
• servers/resources/decoder_capability_matrix.yaml
• servers/resources/decoder_workload_templates.yaml