E2SA-SPADE

Scaffold and register a new E2SA skill so the steps are never half-done. Use when the human or agent wants to create a new capability — "add a skill", "create a new skill", "scaffold a skill", "make this reusable as a skill", "distill X into a skill". Creates the SKILL.md with correct frontmatter, registers it in the AGENTS.md capability catalog (the manual registry), seeds a Changelog, and stops for human review before commit. Human-gated.

Improve an existing E2SA skill from accumulated evidence, human-gated. Use when a skill missed a step or needs updating, when a lesson/feedback in a skill's domain has 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 (lessons, run-journal outcomes, feedback), proposes a concrete SKILL.md diff, and STOPS for human approval; it never self-applies. After approval it edits, appends a Changelog line, and commits.

Implement a new E2SA data-source adapter (the code that fetches a source and parses it into Observation records). Use when writing the adapter for a source that has already been onboarded/inspected — "build the adapter for X", "write the X adapter", "implement the fetch/parse for X", or the coding step after e2sa-add-data-source. Walks the BaseAdapter contract (list_available / fetch / parse_to_schema), the FetchResult single-file-vs-whole-package shape, the Observation + Provenance schema, canonical units + depth + serves, ADAPTER_REGISTRY registration, the fixture + test, and the parse gotchas already learned (sentinels, CRS tiers, obs_id uniqueness, schema drift, idempotency).

Implement a new E2SA data-center connector (the per-data-center access layer that owns auth + search + whole-package fetch under Option C). Use when wrapping a data center not yet connected — "add a connector for X", "wrap the PANGAEA/Earthdata/Zenodo API", or when migrating an existing self-fetching adapter onto a connector. Walks the BaseConnector contract, the probe-the-API-first step, the two search patterns (server-side filter vs enrich + bbox coverage-ratio), the two fetch shapes (BagIt-zip vs file-by-file), the reusable conventions (urllib + User-Agent, raw layout, token-free reads, on-disk fast-path, manual fallback), CONNECTOR_REGISTRY registration, and the mocked-urlopen + E2E_LIVE test split. Distilled from the arctic_data_center and ess_dive connectors.

Add a new data source (data center, archive, or dataset) into an E2SA project. Use when the human or agent has found a dataset to bring in, is inspecting a new archive, or says "add a data source", "add this dataset", "I found data at X", or after downloading data from a center not yet documented. Walks the full procedure: inventory check, download whole package, inspect (format/metadata-standard/CRS/license/citation), write the project-named source card, update the sources index and data-center registry, capture a finding, and credential setup. Always uses the latest dataset version and records a full citation.

Audit an E2SA adapter's data output against the REAL source and propose source-grounded corrections (applied only on human approval). Use after building or changing an adapter, after a parse, when staged data looks off, or for a periodic adapter review — "audit/validate the X adapter", "check the data X produces", "is above_stdm correct", "review the adapters for data-quality". Runs the e2sa/qc checks (serves-subset, value-range, subsurface-depth, citation-not-synthesized, self-describing) on a real parse, surfaces the value distributions, cross-checks variables/units/citation against the source, and PROPOSES a source-grounded fix for each finding (never invents) that is applied only on human approval (propose-first, like e2sa-refine-skill). NOT for run-level shippability (run skeleton / notebooks / secrets / a run_id) — that is `e2sa-validate`. Distilled from the 2026-06-23 above_stdm fabrications (reflection 20260623s).

File a data-preparation task into projects/<project>/tasks/ when the current work needs site data that isn't already prepared. Use whenever the agent (not just the human) recognizes a need for forcing data, surface dataset assembly, observations, or QC/analysis that warrants its own request with provenance. Always sets status=requested and surfaces to the human; never auto-executes the filed task in the same fire.

Produce a publication-quality study-site / watershed / regional map figure for an E2SA project, from public-data download through layered matplotlib rendering. Use when the user wants to "make a site/study-area/watershed map", "plot a DEM map with sites overlaid and labeled", "download a DEM and plot it", "stage HUC-8 boundaries", "build the overview/region figure", or "add/rescope a study site". The config-driven reference scripts live in projects/spade/tools/site_figure/. The report agent's mapping step (E2SA S9) is a downstream consumer. NOT for conceptual/architecture diagrams (use proposal-figure), data/time-series plots, or slides.

Bootstrap a new E2SA project or run. Creates projects/<project>/runs/<run_id>/ with the canonical skeleton (RESEARCH_PLAN.md, REPORT.md, run.yaml, notebooks/, data/, figures/). Always fires first when a new run begins; the human asking for analysis directly does not get to skip it.

Auto-fire on any stage failure, retry, data surprise, or performance issue. Capture E2SA-specific operational lessons (data-adapter quirks, geospatial reprojection traps, schema mismatches, model-training divergences, JupyterHub/cluster environment issues) so the same trap is not hit twice. Writes to memory/knowledge/lessons/. Not user-invocable.

Deterministic structural checks on a run (no LLM call). Verifies the per-run skeleton is complete, notebooks have saved outputs, no hardcoded secrets, no derived-from-script notebook helpers, requirements.txt matches imports, schemas valid, provenance complete, tests pass. Backs the `e2sa validate <run_id>` CLI. Fast (seconds), rule-based.