A2MC-elm

First-run interactive setup for the offline agent — the official "getting started" flow the FIRST time someone uses A2MC in a repo/site. Interview the user (is a2mc_config.sh set up, where is the E3SM/ELM-FATES checkout, FATES on/off, carbon-only vs nutrient-enabled PARTEH, ECA vs RD, site name/location, PFTs, calibration targets), verify the checkout + RAG milestone, then create and populate the use case (site config + validation targets + parameter list) and hand off to phase0-design. Use when the user says "set up A2MC", "first time using A2MC", "help me get started / onboard me to A2MC", "initialize a new site / use case", "configure A2MC for my site", "I want to calibrate a new site". DISTINCT from onboard-session (which resumes an ALREADY-configured setup).

Scaffold + register (or retire + de-register) an A2MC skill so the registry steps are never half-done. Use when the user or agent wants to create a new capability — "add a skill", "create/scaffold a skill", "make this reusable as a skill", "distill X into a skill" — OR to remove one — "remove/retire/delete the X skill". Writes (or deletes) the SKILL.md, and registers (or de-registers) it across all THREE human-facing registries (the README 'Current skills' table, docs/a2mc_reference/skills_catalog.md, AND the AGENTS.md 'At a glance' table), runs the mechanical drift check, and stops for human review before commit. Human-gated.

Set up real-time monitoring of an active A2MC HPC ensemble or experiment on Perlmutter at session start (CLAUDE.md Rule

Log interactive calibration work for a site under use_cases/{site}/memory/logs/. Two log types — a PHASE log (a diagnosis, screening, experiment design/result, refinement — recorded the same way the autonomous agent does, via PhaseLogger, so both modes' logs synthesize together) or a free-form SESSION log (exploratory work that does not map to a specific phase). Use when the user wants to record calibration or exploration work — "log this", "log this phase / diagnosis / experiment", "log this calibration session", "write a session log", "record what I explored".

Compare A2MC calibration rounds (R1, R2, …) against each other and the validation targets — top-N best-achievable biomass per round, per-target Morris μ* sensitivity, P-pool / cross-regime overlays. Use when the user asks to "compare rounds", "update the multi-round figure", "refresh the R1-RN comparison", "which round is best", "top sensitive parameters per round", or to regenerate any `multiround_*` / cross-round figure after new cases complete. Codifies the multiround bundle pipeline + the footguns (screening contamination, case-name patterns, μ* ranking, param-set mismatch, partial-ensemble caveats).

Inject a human-originated domain fact (a discovery, a parameter insight, a mechanism/relationship) into A2MC's curated knowledge so the calibration agent surfaces it — placing it correctly across the up-to-three channels (site discoveries.json, generic parameters.json, curated_relationships.yaml), validating, and rebuilding the graph. Use when the user says "add this finding/parameter knowledge to A2MC's AI", "inject the X discovery into the KB", "make the agent aware of X", "author a curated relationship for X", or wants a manuscript/literature insight to reach the reasoning pipeline. This is the HUMAN-originated counterpart to curate-knowledge (which promotes run-originated proposals); both are Tier-3 curated writes and you (the human-in-the-loop) own the truth call. Distilled from graphrag_curated_yaml_roadmap.md + dev log 20260519d (the clumping_index injection).

Convert a Markdown document (an ana_log, report, or note) to a shareable PDF or Word (.docx) via pandoc. Use when the user asks to "convert/render markdown to PDF/Word/docx", "render this ana_log/report to PDF", "export markdown to a document", "make a PDF of this", "turn this .md into a docx". Prose documents, not slide decks (slides go through Marp). Requires pandoc + a LaTeX engine for PDF, and python-docx for round-trip-safe .docx edits. Self-contained repo copy — depends only on tools the environment provides, not on any user-level skill or ~/.claude workflow.

Design + launch + analyze an A2MC offline HPC experiment (parameter sweep on top of a Morris base case). Use when the user wants to test a hypothesis with N variant runs (e.g., clumping_index sweep, vmax_p sensitivity, hydraulic-vulnerability probe). Codifies the conventions distributed across phases/phase5_testing/, tools/create_case.sh --case-suffix, and prior per-experiment plans in memory/dev_logs/.

Cold-start runbook — orient at the start of a session or after a context reset/compaction. Use when a session begins, resumes, or is compacted (especially if the SessionStart snapshot shows in-flight work or pending proposals), or when the user says "catch up", "where did we leave off", "onboard", "what's the current state". Reads the latest handoff, re-reads CLAUDE.md, checks live HPC processes + run state, and hands off to arm-hpc-monitoring / curate-knowledge as needed.

Run Phase 0 (DESIGN) of the A2MC calibration workflow as the offline agent — the human-in-the-loop analog of the orchestrator's `_run_design()`. Sample the parameter space (Morris/Sobol/LHS), materialize one FATES parameter file per case, generate + build + submit the ensemble, and arm monitoring. Use when the user says "design a new round", "set up the ensemble", "sample the parameters", "submit the Morris ensemble", "start a calibration round", "expand the parameter space (redesign)".

Run Phase 1 (EXPLORATION) of the A2MC calibration workflow as the offline agent — the human-in-the-loop analog of the orchestrator's `_run_exploration()` / `reasoning.analyze_sensitivity_results()`. Extract the Y matrix from completed simulations, run Morris sensitivity analysis, and interpret μ* to decide what parameters matter for each target/PFT. Use when the user says "run the sensitivity analysis", "extract the Y matrix", "which parameters matter", "run Phase 1", "Morris rankings", after the Phase 0 ensemble finishes.

Run Phase 2 (SCREENING) of the A2MC calibration workflow as the offline agent — the human-in-the-loop analog of the orchestrator's `_run_screening()` / `reasoning.analyze_screening_results()`. Rank the ensemble against the validation targets (RMSRE, targets-satisfied), find the best / lowest-cost / most-targets cases, read the error/bias patterns, and route the round into Phase 3 diagnosis. Use when the user says "screen the ensemble", "rank against targets", "which case is best", "run Phase 2", "how many targets are met", after Phase 1 sensitivity.

Run Phase 3 (DIAGNOSIS) of the A2MC calibration workflow as the offline agent — the human-in-the-loop analog of the autonomous orchestrator's `_run_diagnosis()` / `reasoning.diagnose()`. Systematically root-cause WHY the screening round is missing its validation targets — gather diagnostic data with the phase3 tools, pull RAG + Adaptive Memory context, then reason to a structured diagnosis (failing targets, likely causes, ranked root causes, parameter recommendations, base cases, hypotheses) and hand off to Phase 4. Use when the user says "diagnose the failing targets", "run Phase 3", "why aren't the targets calibrating", "root-cause this round", "what's driving the PFTx miss", after screening (Phase 2) hands off a ranked ensemble.

Run Phase 4 (HYPOTHESIS) of the A2MC calibration workflow as the offline agent — the human-in-the-loop analog of the orchestrator's `_run_hypothesis()` / `reasoning.generate_hypothesis()`. Turn a Phase 3 diagnosis into specific, testable hypotheses with parameter changes + expected outcomes, and FIRST try to test them against the existing Morris ensemble (skip-testing — reads existing data, no new simulations) before committing to a Phase 5 experiment. Use when the user says "generate a hypothesis", "what should we test next", "design the experiment", "can we test this with existing data", "run Phase 4", after Phase 3 diagnosis.

Run Phase 5 (TESTING) of the A2MC calibration workflow as the offline agent — the human-in-the-loop analog of the orchestrator's `_run_testing()`. Execute the hypothesis experiments as new simulation runs — modify parameter files, create + submit cases (ADSP→RGSP→TRANS), monitor, and extract results against targets. This is a thin phase-router — the end-to-end offline procedure lives in `offline-testing-workflow`. Use when the user says "run the experiment", "submit the test cases", "run Phase 5", "test this hypothesis with new simulations", after Phase 4 hands off a hypothesis that needs new simulations.

Run Phase 6 (REFINEMENT) of the A2MC calibration workflow as the offline agent — the human-in-the-loop analog of the orchestrator's `_run_refinement()` / `reasoning.interpret_results()` + `extract_lesson()`. Evaluate the experiment results vs baseline + expected outcomes, extract lessons (discoveries / failed approaches), update Adaptive Memory, and decide convergence — converged, rethink (6→3), or redesign (6→0). Use when the user says "evaluate the results", "did the experiment work", "extract the lessons", "run Phase 6", "should we converge or iterate", "what did we learn", after Phase 5 testing.

Rebuild or repair the A2MC RAG/GraphRAG index (ChromaDB vector store + NetworkX knowledge graph) that the ReasoningModule queries before every Claude API call. Use when the user asks to "rebuild the RAG", "reindex", "bump the wiki to a new commit", "the RAG/index stopped working / returns nothing / returns stale content", "I edited the curated YAML — refresh the graph", "add a model to the RAG", or after any edit to a wiki / CDL / curated_relationships.yaml. Codifies the build pipeline + the footguns (the loader pattern-probe symlink trap, --rebuild vs --graph-only, Python 3.10, dropped curated edges, PFT-count env var) distilled from docs/a2mc_reference/rag_build_roadmap.md and the RAG dev logs.

Run a manuscript-supporting scientific investigation that ends in a figure + an ana_log — pose a question, pull ensemble/run data, compute the statistic/mechanism, make a figure, cite evidence, and write an ana_log. Use when the user asks to "investigate whether X", "is X correlated with Y", "analyze the mechanism of X", "make a manuscript figure for X", "P-pool / cross-regime / attribution analysis". For a standardized single-round report use summarize-calibration-round; for cross-round figures use compare-calibration-rounds.

Produce a one-round calibration summary — whole-ensemble biomass graphs (combined 519-yr axis + TRANS), an evaluation report (best case,

Validate the source→wiki→curated-YAML→RAG chain before shipping, using the three A2MC validators in dependency order. Use when the user asks to "validate the wiki/RAG", "check the wiki against source", "did the rebuild regress", "check for hallucinations before merging the wiki", "validate the curated YAML", or after generating a wiki / editing curated_relationships.yaml / rebuilding the RAG at a new commit. Runs codebase_wiki_validator (wiki↔source) → yaml_wiki_validator (YAML↔wiki+param+output) → rag_diff (profile vs reference), applies the Green/Yellow/Red banding and the fabrication-vs-false-positive triage. Distilled from docs/a2mc_reference/rag_validation_workflow.md.

Construct the entire RAG/GraphRAG knowledge layer from scratch when the index AND/OR its inputs don't exist yet — either reconstructing an existing model's full layer from source (api-31-0 reproducibility / disaster recovery) or bootstrapping a brand-new model (EcoSim, ReSOM, …) into A2MC. This is the orchestrator that sequences the four step-skills (generate-codebase-wiki → build → inject-knowledge/curated-YAML → validate-rag-chain) plus the glue none of them own (loader registration, per-model parsers, separate persist dirs, milestone registration). Use when the user says "build the RAG/GraphRAG from scratch", "set up RAG for a new model", "add EcoSim/ReSOM to A2MC", "reconstruct the whole knowledge layer", "bootstrap the knowledge base from nothing". For reindexing inputs that already exist, use rebuild-rag instead. Distilled from rag_build_roadmap.md (Recipe 2) + codebase_wiki_generation_roadmap.md (Recipe B3).

Review and promote staged Tier-3 knowledge proposals (the human-in-the-loop curation step that pairs with the memory write gate). Use when the user asks to "review/curate pending knowledge", "promote proposals", "what did the runs propose to learn", "check auto_discovered_pending", or at session start when staged proposals exist. The autonomous online agent stages auto_learn proposals to auto_discovered_pending.json instead of the curated KB; this skill evaluates each against evidence and promotes the vetted ones (or discards misunderstandings).

Investigate an anomaly or suspicious result in an ensemble — an outlier, a too-good "best" case, a failure cluster, a target that won't move — to determine FIRST whether it's real or an artifact (contamination, infra-timing, mislabeled index, NaN), then root-cause it with the phase3 diagnosis tools. Use when the user asks "why is case X an outlier", "is this result real or contamination", "investigate this anomaly / failure cluster", "edge-case / collapse detection", "root cause of this PFT not calibrating".

Produce a source-grounded codebase wiki for a model (FATES, ELM, EcoSim, ReSOM, or a new target) by fanning out parallel subagents that read actual source and cite (file:line) — the foundation every downstream A2MC artifact (RAG vector index, knowledge graph, calibration prompts) is built on. Use when the user asks to "generate/build a codebase wiki", "the deepwiki/cursor wiki is wrong — rewrite it", "audit the wiki against source", "bump the wiki to commit X", or "add model Y to A2MC" (wiki is step 1). Picks Workflow A (greenfield) vs B (audit-then-rewrite), enforces the fabrication/citation gates and commit-pinned output convention. Distilled from docs/a2mc_reference/codebase_wiki_generation_roadmap.md and the FATES/ELM/EcoSIM wiki dev logs.

Improve an existing A2MC skill from accumulated evidence, human-gated. Use when a skill missed a step or needs updating, when dev_logs/ana_logs/verify-pass findings in a skill's domain have piled up, or during a periodic skill review — "refine the X skill", "improve this skill", "the X skill should have caught Y", "review the skills". Gathers the signal (dev_logs, ana_logs, verify findings, explicit corrections), proposes a concrete SKILL.md diff with cited evidence, and STOPS for human approval; it never self-applies. After approval it edits, appends a

Restart SLURM jobs that failed in an A2MC ensemble or experiment. Use when failures appear mid-run (NODE_FAIL, PartitionDown, SIGKILL clusters) or at end-of-run (model failures like runaway recruitment, FATES mass-balance, PARTEH abort). Distinguishes infrastructure (restart-eligible) from model failures (NOT restart-eligible without parameter/model fix). Picks between `tools/diagnose_ensemble_status.py` (quiescent ensemble) and the `sacct`-based TSV pathway (in-flight ensemble). Generates audit TSV + flat case-list, handles two-wave zombie cleanup, and submits restart via `submit_phase0.py --cases-file`.