research-workflow

Ledger of a result's assumptions and approvals (value sources → provenance). Use when a result or model rests on simplifying assumptions, approximations, fixed parameters, or regime-of-validity choices, and whenever a scientific assumption is proposed or approved — keep one running ledger of each assumption, who approved it, its regime, and which results depend on it, so a broken assumption leads to a known, bounded re-check. Don't use for citing the source of a value (→ provenance), recording a decision and its rationale (→ decision-log-and-commits), quantifying the numeric error a kept assumption induces (→ uncertainty-reporting-gate), or noting a regime or caveat a *paper* established as you read it (→ literature-workflow).

Write benchmark and scaling tests (reading timings → performance-measurement). Use when verifying performance claims, characterizing scaling, comparing implementations, or validating against analytic solutions for performance-critical kernels (integrators, force solvers, renderers) — this generates the benchmark/validation code. Don't use for small analysis scripts (overkill), planning invariants and diagnostics before code exists (→ numerical-method-validation), the measure-first method or interpreting strong/weak scaling results (→ performance-measurement), or JAX compile-boundary performance (→ jax-performance).

Review code organization and docs (physics/numerics → scientific-code-reviewer). Use when reviewing code organization, abstraction/DRY, and docs (docstrings, README, guides) for scientific-computing repos — research-code pragmatism, not enterprise patterns. Don't use for physics/units correctness or numerical stability (→ scientific-code-reviewer), or JAX mechanics (→ jax-code-validator).

Replace wrong-ownership code with a direct cutover, no compat layers or aliases. Use when existing API/control-flow/canonical code encodes scientifically wrong ownership and compatibility-preserving edits (wrappers, aliases, adapters, reporting glue) would keep the wrong path alive — break it cleanly instead. Don't use while still diagnosing whether the structure is wrong (→ ownership-and-structure) or to scope the smallest change (→ minimal-falsifiable-slice).

Review data save/load code — format, units metadata, precision, portability. Use when reviewing data loading/saving code, before archiving simulation outputs, or when setting up data pipelines. Reviews portability, metadata preservation, format choices, and long-term reproducibility. Don't use for data-file or constant provenance (→ provenance), or scientific correctness of the data values (→ scientific-code-reviewer).

Record physics/architecture decisions and write scoped research commits. Use either when capturing a nontrivial physics/architecture decision (record chosen / rejected / what-would-reverse-it while the reasoning is fresh) OR when landing changes so commits stay single-purpose and evidence-backed. Don't use for the close-out verification format (→ verification-gate) or archiving run artifacts and dated notes (→ run-reproducibility).

Derive a non-trivial formula or an experiment's prediction before code or runs. Use when about to implement any non-trivial formula, algorithm step, or transformation, or to state the prediction an experiment will be judged against — gate that the math is derived from a stated starting point (or cited to a specific equation, or a postulate the researcher has declared) and dimensionally/limit-checked BEFORE it becomes code, so you implement a result you verified rather than one you guessed. Don't use for citing the source of a constant/coefficient (→ provenance), proving a scheme converges at its order (→ numerical-method-validation), or the session stance on which choices need the researcher's approval (→ researcher-in-the-loop).

Write MyST docs prose and page structure in house voice (syntax → myst-expert). Use when writing or revising PROSE *or page structure* for the researcher's MyST research documentation (software-package docs, knowledge-hub sites, design/ADR docs) — to match the plugin's default house voice (motivate→frame→formalize, serve new graduate students AND professors at once, quantitative CGS/solar anchoring, active/second-person) AND its docs-as-knowledge-ecosystem page rules (what each page type must contain, how theory↔API↔validation↔references cross-link, onboarding paths); a project can override the house voice. Delegates base prose clarity to elements-of-style:writing-clearly-and-concisely. Don't use for manuscripts/telescope proposals (→ writing-science-voice), grants (→ grant-writing-voice), MyST syntax/project config (→ myst-expert), or visual layout conventions (the project's own style guide or frontend tooling).

Log disagreements among paper, errata, extraction, reference code, and our code. Use when an equation, coefficient, variable definition, table, erratum, reference implementation, or local test disagrees with another source. Don't use for routine extraction with no contradiction (→ pdf-equation-extraction) or for final code translation once the source is settled (→ equation-to-code-traceability).

Turn verified equation-digest rows into code and tests with traceable links. Use when translating verified equation-digest rows into code, tests, specs, notebooks, or benchmark fixtures. Don't use to extract equations from PDFs (→ pdf-equation-extraction), to decide reference-code license boundaries (→ reference-license-firewall), or to resolve conflicting sources (→ equation-errata-ledger).

Validate gradients (FD grad-checks, NaN/zero grads), not forward convergence. Use when validating that the GRADIENTS of a differentiable model are correct (not just the forward value) — finite-difference grad-checks, NaN/Inf under jax.grad, and silent zero/blocked gradients from stop_gradient, argmax/argsort, where() with a singular dead branch, or clip/floor saturation. Don't use for forward-method convergence/conservation (→ numerical-method-validation) or reviewing JAX tracing mechanics in already-written code (→ jax-code-validator).

Test stance — falsifiable hypothesis, rival, and cheapest discriminating run. Use once a claim is at stake or a costly test is about to be designed (model-development's Test stance) — sharpen ONE direction into a falsifiable hypothesis with a named rival, the discriminating observable, and a kill criterion, then design the cheapest run that separates the hypotheses (expected signature under each, smallest configuration, decision rule fixed before running). Don't use while the model is still being developed or can't yet predict distinct signatures (→ model-development), to generate many candidate directions (→ research-ideation), to scope the code change that runs the test (→ minimal-falsifiable-slice), or for software design brainstorming (use superpowers brainstorming).

Review JAX tracing/jit/PRNG/pytree/vmap correctness (speed → jax-performance). Use when reviewing JAX code for tracing/JIT, PRNG, pytree, and vmap correctness — the traps that either raise at trace time or, worse, compile fine and silently compute the wrong thing (numpy RNG frozen into a constant, leaked tracers, a vmap over the wrong axis). Don't use for physics/units correctness or numerical stability (→ scientific-code-reviewer), gradient correctness (→ gradient-validation), or compile/transfer performance (→ jax-performance).

Speed up slow or memory-bound JAX — recompiles, transfers, donation, sharding. Use when JAX research code is slow or memory-bound — diagnose and fix recompilation (changing shapes or Python-level control flow), unnecessary host-device transfers, missing donate_argnums, and multi-device sharding (jit with shardings, shard_map), and time JAX correctly with block_until_ready. Don't use for JAX tracing/correctness bugs like leaked tracers or wrong vmap axes (→ jax-code-validator), or the general measure-first method and parallel scaling curves (→ performance-measurement).

Bound a test or cutover to the smallest code slice (not exploratory work). Use when you've decided WHAT to change and need to bound it to the smallest code slice that can prove or falsify ONE scientific claim — naming the exact files to touch, the files NOT to touch, and the single run that settles it — instead of a broad multi-purpose rewrite. Applies to test and cutover slices, not to open exploratory work with the researcher. Don't use to design the experiment/decision-rule itself (→ hypothesis-and-test-design), when the real problem is a wrong owner preserved by wrappers (→ correct-cutover), or a confirmed structural mismatch (→ ownership-and-structure).

Develop the researcher's own model on its terms — derive consequences, closures. Use when the researcher brings their OWN model, closure, constitutive relation, or phenomenological assumption and wants it developed — or poses an open theoretical question to explore — before any claim is being tested. Adopt the model provisionally, derive its consequences on its own terms, expose missing closures and internal inconsistencies with candidate completions for the researcher to choose, and pick the next calculation that most improves understanding. Sets the SCIENCE stance (Explore / Develop / Critique / Test). Don't use to generate rival research directions (→ research-ideation), to sharpen a direction into a falsifiable hypothesis and design the discriminating run once a claim is at stake (→ hypothesis-and-test-design), or to red-team a finished result (→ adversarial-result-check).

MyST/mystmd syntax, config and deploy (prose voice → docs-writing-voice). Use when authoring, fixing, or deploying MyST (mystmd) content — colon-fence directives, roles, admonitions, cards/grids/tabs, figures, tables, KaTeX math, cross-references (`(label)=` + `[](#label)`), citations (`[@key]`), `myst.yml` and frontmatter, exports (PDF/LaTeX/Typst/DOCX), GitHub Actions deploy to Pages (working dir, BASE_URL for sub-path sites), and cross-project xref federation (`project.references`, `myst.xref.json`). Grounds you in the NEW mystmd, which differs from legacy Sphinx-MyST (no `conf.py`, Pandoc-style citations, cross-refs as Markdown links, KaTeX not MathJax). Don't use for a site's visual layout conventions (the project's own style guide or frontend tooling), Quarto (→ quarto-expert), prose voice (→ docs-writing-voice), or writing `.mjs` plugins and interactive-figure directives (→ mystmd-plugin-dev).

Record failed, null, or contradicting results honestly; no p-hacking or burying. Use when an experiment, fit, or test fails, shows no effect, or contradicts the hypothesis — gate that the negative result is recorded honestly rather than buried, deleted, or retried with new settings until it flips. A non-effect is a result. Don't use for logging successful runs in general (→ run-reproducibility), recording a design decision and its rationale (→ decision-log-and-commits), or red-teaming a positive result you already believe (→ adversarial-result-check).

Validate a method against its theory — convergence order, invariants, baselines. Use when validating a numerical method against its own theory — convergence/order-of-accuracy refinement studies, conservation/invariant checks to tolerance, oracle strategies (manufactured solutions, self-convergence, symmetry/limit checks) when no analytic truth exists, and persisting a regression baseline so verified behavior cannot silently drift. Don't use for parity against a reference implementation (→ reference-parity-audit), the general close-out format (→ verification-gate), or auditing someone else's numerics in review (→ scientific-code-reviewer).

Floating-point pitfalls — float32 vs x64, cancellation, precision floors. Use when writing or reviewing numerical code where floating-point representation can corrupt results — choosing float32 vs float64, guarding catastrophic cancellation, bounding overflow/underflow, and stopping NaN/Inf propagation, and being explicit about dtype across a pipeline (especially JAX, which defaults to float32). Gate that precision is a deliberate, justified choice and that the known FP hazards at that precision are handled. Don't use for whether a method converges at its theoretical order (→ numerical-method-validation), whether gradients are correct/finite (→ gradient-validation), or citing a constant's source (→ provenance).

Who owns each equation/BC/source term; stop when the architecture is wrong. Use when changing or reviewing solver/IC/mesh/boundary/source/diagnostics code in a research codebase — map who owns each quantity/equation/acceptance decision, define canonical vs legacy lanes, and stop tuning when the architecture itself is structurally wrong. The slash-list above is examples, not a checklist. Don't use to execute the break once a wrong owner is confirmed (→ correct-cutover) or for the close-out evidence format (→ verification-gate).

Extract implementation-critical equations/coefficients from PDFs, verified. Use when extracting, auditing, or preparing implementation-critical equations, coefficient tables, phase definitions, or derivations from PDFs, especially old, scanned, two-column, or OCR-hostile papers. Don't use for ordinary source summaries, for translating already verified equations into code (→ equation-to-code-traceability), or for licensing questions around reference code (→ reference-license-firewall).

Profile before optimizing; measure speedups and strong/weak scaling correctly. Use before optimizing research code or claiming it is fast or scales — measure first on a representative workload, attribute the cost, fix the dominant term, and prove the speedup against a baseline with the science unchanged; for parallel code, measure strong and weak scaling with efficiency, name the breaking point (Karp–Flatt separates serial fraction from overhead), and hold work per worker fixed for O(N²) kernels. Don't use for JAX recompilation, host-device transfers, or sharding mechanics (→ jax-performance), generating the benchmark code itself (→ benchmark-generator), or recording a cluster job's provenance (→ run-reproducibility).

License boundaries when reference code informs an implementation (clean room). Use when a paper implementation will be compared against or informed by reference code, especially GPL, unclear, or differently licensed repositories. Don't use for ordinary citation provenance (→ provenance), for PDF equation extraction (→ pdf-equation-extraction), or for same-license internal refactors.

End-stage parity audit vs a reference code at physical landmarks (e.g. MESA). Use at or near the end of a development campaign — before a result is published, released, or claimed to match — when a change claims parity with a reference implementation or published numerical result (e.g. MESA, a published code or dataset) and you need a file-backed audit of how the reference actually works plus checkpoint-matched comparison at physical landmarks — not vague "looks like" trajectory similarity. Don't use mid-development to demand a reference-code run (magnitude, physics, and analytic checks the researcher accepts carry development), or for general close-out verification (→ verification-gate, which owns Validation stages), or for validating a method against its own theory including comparison to an analytic/manufactured solution (→ numerical-method-validation).

Generate and rank candidate research directions (not developing your own model). Use at the very start of research — when you have an interest area, an unexplained observation, a new dataset, a new method or capability, or a vague "there might be something here" — to generate many candidate research directions and triage them into a ranked shortlist scored on novelty, feasibility, and impact. The divergent front of the funnel. Don't use when the researcher already has a model or closure they want developed (→ model-development), to sharpen one chosen idea into a hypothesis and design its test (→ hypothesis-and-test-design), or to package chosen directions into fundable proposal aims (use the grant-writing grant-specific-aims skill).

Release research code — version, CITATION.cff, archived DOI, figures regenerate. Use when cutting a release of research code, pairing software to a paper, or making code citable — semantic versioning, changelog, CITATION.cff with ORCID and CRediT roles, archiving the exact version under a persistent identifier the paper cites, the "every published figure regenerates from the release" check, and confirming the external-validation milestone is done. Don't use for recording individual runs or the environment (→ run-reproducibility), the validation stages themselves (→ verification-gate), or a funder data management plan (grant-writing grant-budget-and-docs).

Researcher approves scientific choices; propose derivation-backed experiments. Use at the start of any research-code session and whenever a scientific choice, an experiment, or a high-impact action comes up — the researcher is the PI-level collaborator who owns the science. Covers which choices need their approval (closures, parameters, approximations, regimes, boundary conditions, anything that changes the physics) versus mechanical choices you make and state; how to propose an experiment (physical motivation, derived prediction, run definition, cost) and run it once approved; high-level direction (stance first; options and a recommendation for decisions); and the checkpoints before changing equation/boundary/source-term ownership, breaking an API, replacing a canonical lane, or exceeding the cost threshold. Don't use for the evidence close-out (→ verification-gate) or developing the researcher's own model (→ model-development).

Report numbers as value ± uncertainty with dominant source; seed ensembles. Use when a result is about to be reported as a number — derived quantities, fitted or inferred parameters, energy/momentum budgets, anything from stochastic runs (random seeds, stochastic ICs, Monte Carlo, bootstrap) — to report value ± uncertainty with the dominant source named, judge stochastic results across a seed ensemble rather than one lucky draw, and choose σ vs σ/√N vs σ/√N_eff correctly. Don't use for the pass/fail close-out (→ verification-gate), a method's convergence or conservation (→ numerical-method-validation), sampler diagnostics (→ bayesian-inference-gate), or hunting unmodeled systematics (→ adversarial-result-check).

Evidence for claims of fixed/converged/validated; owns the validation stages. Use while running research commands whose output you will interpret, and before claiming a research task is complete, fixed, converged, validated, or parity-improving — report evidence with units, label each number's validation stage (physics-checked, analytic-checked, externally validated), translate residual norms into the physics they bound, and close out in an evidence-first format sized to the change. Owns the canonical Validation stages. Don't use for validating a numerical method against its theory (→ numerical-method-validation), the parity audit itself (→ reference-parity-audit), or recording runs across sessions (→ run-reproducibility).