Use when adding a unit or integration test, writing a new Catch2 TEST_CASE, scaffolding a test fixture, starting TDD work, OR figuring out how to run / filter / debug Catch2 tests flexibly. Trigger on "add a test", "write a test for", "I need test coverage", "TDD this", "run just this test", "how do I filter tests by tag", "Catch2 generators", "Catch2 sections", "Catch2 matchers", "reproduce a random-order failure". Enforces Catch2 v3.14.0 patterns, the one-test-one-implementation TDD discipline, the layer-direction rule for test sources, and the tests/<layer>/<file>_test.cpp layout convention. The Catch2 idiom cheat sheet and the bench-binary invocation reference live as separate files under `references/`, loaded on demand when the workflow steps point to them.
Use when clang-tidy reports a violation that needs to be addressed, when adding a NOLINT suppression of any kind, when a function approaches the cognitive-complexity ceiling, or when invoking clang-tidy directly. Trigger on "clang-tidy says...", "I need to suppress this warning", "NOLINT", "NOLINTBEGIN", "this function is too complex", "should I refactor or NOLINT", "is it OK to use clang-tidy --fix", "what's the right NOLINT form for this case". Walks the procedure for resolving a clang-tidy violation, the discipline for justifying and shaping NOLINT suppressions, the complexity ceiling that gates further function growth, and the project-specific reason `clang-tidy --fix` is forbidden. Defers to docs_dev/style/cpp_style.md for the canonical rule statements.
Use when adding a new source file, a new dependency, a new build target, a new build option, or when changing how an existing target links or compiles. Trigger on "I added a new .cpp file; do I need to update CMakeLists?", "add this new dep", "the test isn't being built", "what does LANCET_PROFILE_MODE do?", "the new layer needs its own library target", "this header isn't being installed". Walks the dependency declaration → target wiring → option propagation chain so all four pieces stay coordinated. Aware of the sanitizer build trees (LANCET_SANITIZE_BUILD), the profiling tree (LANCET_PROFILE_MODE), the static-link option (LANCET_BUILD_STATIC), and the test/benchmark inclusion options. Does NOT cover modifying the cmake/ subdirectory's superbuild fragments — those are protected and changes there go through normal review.
Use when proposing to add, remove, rename, change cardinality of, or silently change semantics of a VCF FORMAT, INFO, or FILTER field, OR when changing a user-facing CLI flag (rename, default, semantics). Trigger on "add a FORMAT field", "rename SB to STRBIAS", "change AD from R to A", "deprecate this field", "the field still exists but means something different now", "rename the --tumor flag", "change the default for --num-threads". Walks the user through a 5-operation matrix (add / rename / cardinality-change / remove / silent-semantic-change), produces a coordinated edit set across vcf_header_builder.cpp + caller code + tests + docs, contributes a structured paragraph to the commit body, and invokes the vcf-validator subagent before finalizing. Does NOT cover internal struct fields or non-VCF data formats — those go through normal review.
Use whenever running, planning, or troubleshooting Lancet2's probe variant forensic pipeline — the three-step workflow of truth_concordance.py → Lancet2 with --probe-variants/--probe-results → analyze_probe_results.py. Covers operational mechanics: which inputs go where, the flag dance between steps, the data layout, --verbose requirements, and how to derive paths for the somatic case (currently lacks truth VCFs). Use proactively when the user mentions probe tracking, missed variants, truth concordance, lost_at_stage, sensitivity debugging, or specificity debugging. For interpretation of an existing report — "what does this funnel mean, where do I dig in next?" — delegate to the `probe-interpreter` subagent instead.
Use when changing a Python script under scripts/, when changing C++ code that a Python script consumes, or when figuring out which Python script to reach for. Trigger on "I just changed analyze_profile.py", "the C++ probe-results format changed; does analyze_probe_results.py need an update?", "what does run_clang_tidy.py do?", "which script generates the walk palette?", "the export_docs.py is producing wrong output". Maintains the contract between the C++ pipeline and the Python tooling that consumes its output, runs lint-style checks on script edits, and surfaces drift between scripts and the project conventions they implement (clang-tidy invocation, format checks, IWYU). Scoped to scripts/*.py and scripts/*.sh; does NOT cover Python under tests/ (those are C++ test fixtures, not pipeline tooling) or Python under docs/ (those are mkdocs plugins).
Use when investigating a crash, intermittent test failure, suspected data race, memory error, or any sanitizer-detectable bug, AND the goal is to land a fix with a regression test. Trigger on "this crashes", "race condition", "use-after-free", "ASan says", "TSan reports", "MSan", "UBSan", "intermittent flake in tests/". Drives pixi-managed sanitizer build trees (cmake-build-asan, cmake-build-msan, cmake-build-tsan, cmake-build-ubsan), reproduces the failure, hands the trace to the sanitizer-expert agent for analysis, and lands the minimum fix with a regression test. Per-sanitizer detail (what each catches, runtime options, common findings, the mimalloc-coverage caveat) lives in references/sanitizer_matrix.md, loaded on demand. For analysis-only of an existing report, use the sanitizer-expert subagent instead.
Use whenever the user asks "which test data should I use", "what's in the dataset", "which BAM has X", or when planning a test/benchmark/sanitizer run and you need to pick the right fixture. Documents every file at gs://lancet2-test-datasets/test_harness_data/, the env vars that map to them, and which fixture fits which workflow (somatic, germline, truth comparison, T2T, longdust calibration). Read-only reference.