Skip to content

bioepic-data/ecosim-agent / .agents/skills/ecosim-plant-trait-sanity-check

ecosim-plant-trait-sanity-check

Verified

Read-only validation of EcoSIM plant_trait.*.desc values for the first grid, including all plant-class identities and their evidence coverage, C3/C4 physiology, active protein allocation and root hydraulics. Use for trait evaluation and run-readiness checks. Never edit or replace the `.desc` file.

EcoSIM Plant Trait Sanity Check

Overview

Use this skill to sanity-check EcoSIM plant_trait.*.desc files. These files are strictly read-only: never edit, overwrite, patch, or generate a replacement .desc file. Each PLANT traits for FUNCTIONAL TYPE block represents one plant, and the default check is intentionally confined to the first grid only: NY=1, NX=1. All active plant blocks at that grid are checked.

The check has two layers:

  • deterministic file checks for malformed values, units, ranges, and block consistency
  • web-informed ecological checks using species, genus, or plant-functional-type evidence gathered during the task

PLANT CLASS INFORMATION must be validation-based. For every selected PFT, validate all 14 class items against active model codes/labels and applicable plant/site evidence. Read the mandatory class validation contract. Parsing, a valid enum, a PFT-name heuristic or absence of findings is not ecological validation. Report each item as validated, invalid, contradicted or unresolved; missing evidence must stay visible. The description stays read-only.

Always back parameter-value judgments for plant_trait.*.desc files with web search unless the user explicitly asks for an offline/local-only check. Treat deterministic checker results as a first pass, not as sufficient evidence that ecological or physiological parameter values are correct.

Workflow

  1. Locate the target plant_trait.*.desc file. If the user gives no path, prefer a local path they recently mentioned, then search under data/, then under the repository.
  2. For calibration or run readiness, run the deterministic checker in strict physiology mode:
python3 .agents/skills/ecosim-plant-trait-sanity-check/scripts/check_plant_trait_desc.py /absolute/path/to/plant_trait.1930.desc --strict-physiology --require-class-evidence --pft-file /absolute/path/to/selected_pft.nc --web-evidence /absolute/path/to/site_evidence.json

Omit --strict-physiology only for an exploratory review where physiological findings should remain warnings. Strict mode promotes physiological-consistency warnings to errors and returns a nonzero status. For an exploratory/offline review, --require-class-evidence may be omitted, but the class verdict remains incomplete when evidence is unresolved. A prescribed sensitivity may retain unsupported choices with that limitation explicitly reported; do not claim scientific readiness or validated classes.

  1. Keep the default grid scope unless the user explicitly asks for another grid. The default is equivalent to:
python3 .agents/skills/ecosim-plant-trait-sanity-check/scripts/check_plant_trait_desc.py /absolute/path/to/plant_trait.1930.desc --ny 1 --nx 1
  1. For a site run, first extract the site vegetation and site trait measurements (scripts/site_vegetation.py extract, then site-evidence), and target the searches at the site's dominant species (see references/web_evidence.md, Site Vegetation First). Use web search to gather trait evidence for each first-grid plant block. Read references/web_evidence.md, then search for the plant name, likely taxon, or functional type plus trait terms. For ndlf35, woak35, US-Me2, or US-xSP/SOAP work, also read references/pft_case_notes.md. Before attributing low GPP or poor phenology to a trait, read the growth-stoichiometry, PTSHT, ZTYPI, and perennial-grass floral-initiation sections of references/sanity_rules.md.
  2. Maintain the mandatory evidence coverage audit for every reviewed PFT and relevant trait group. Record the actual search and its outcome, including groups not searched; a clean checker cannot establish review completeness. Convert the evidence into EcoSIM units and save a persistent site evidence JSON file. Use species-level evidence when available; otherwise use genus, family, or functional-type evidence and mark that evidence level. Combine per-species values by canopy share (site_vegetation.py weight) and run site_vegetation.py lint.
  3. Re-run the checker with the evidence file:
python3 .agents/skills/ecosim-plant-trait-sanity-check/scripts/check_plant_trait_desc.py /absolute/path/to/plant_trait.1930.desc --web-evidence /absolute/path/to/web_evidence.json
  1. Report findings by severity. Lead with ERROR findings, then WARN findings, and include the plant code, grid tuple, parameter name, source line, and web source when applicable.
  2. Report two separate verdicts: parameter screening and literature-review coverage. With zero findings, say only that the selected blocks passed the implemented screens and supplied evidence comparisons. State which trait groups have applicable evidence, which rely on provisional/model/user priors, and which remain unsearched or unresolved. Do not say all traits are supported, ecologically validated, or comprehensively reviewed unless the coverage audit supports that claim. A five-day read-back of one parameter does not complete the site's broader trait review; retain that limited scope.

What Is Checked

The checker validates the plant blocks at the selected grid for:

  • required EcoSIM trait sections
  • parseable finite numeric values in numeric sections
  • fraction variables within [0, 1]
  • positive rates, capacities, dimensions, uptake parameters, resistance terms, and nutrient ratios
  • CLASS as four inclination fractions that sum to one
  • optical albedo plus transmission not exceeding one
  • pathway-specific Rubisco Kc, Ko, carboxylation:oxygenation turnover ratio, and implied CO2/O2 specificity
  • Rubisco and PEPC fractions of total leaf N implied by their allocations within the N/P-limited total leaf-protein pool
  • leaf and root protein C supported jointly by N and P in active structural biomass, with only active root biomass used for woody PFTs
  • C4 protein-normalized Vpmax:Vcmax and a lower-priority, model-formulation-sensitive C3/C4 Jmax:Vcmax diagnostic
  • pathway-specific FCO2, C4 mesophyll chlorophyll partitioning, and PAR/shortwave absorptance
  • total photosynthetic protein allocation without double-counting the shared leaf-protein pool
  • SLA1 against explicit species- or site-specific web evidence, without using SLA to infer photosynthetic kinetics
  • ANGSH = 0 for plant forms without petiole or sheath tissue, including conifer, lichen, and moss PFTs
  • Soybean (soyb*) ANGSH = 45 degrees from horizontal is the user-selected default (2026-11-13). The checker reports other numeric values as user-default warnings, including in strict physiology mode. Respect explicit sensitivity values; keep .desc files read-only. This is a parameter preference, not a literature-derived range, a leaf-inclination CLASS setting, or a validated emergence correction. Use 45 when preparing soybean defaults unless the user specifies another value; apply changes only to the selected parameter NetCDF through ParEditor.
  • osmotic potential sign and standing dead biomass sign
  • growth yield bounds
  • N and P concentration magnitudes
  • all 14 class-information fields: required rows, code domains, label/code and optional selected-PFT consistency, plus mandatory per-item evidence verdicts; the annual-evergreen convention applies to human-seeded annual crops, not all annual vegetation
  • separate thermal-section parsing and finite positive RG/CG/LG inactivation energies when that section is present
  • woody versus herbaceous root trait consistency
  • cross-parameter checks such as PhiMIN <= PhiMAX and fine-root radius not exceeding primary-root radius
  • RSRR radial root resistivity, its implied fully wetted conductivity, and its interaction with soil drying and total root resistance
  • literal RVSR conduit radius, conifer tracheid anatomy, implied conduit count N=0.2*(RRAD2M/RVSR)^2 >= 1 (equivalently RVSR <= sqrt(0.2)*RRAD2M), and ARSRA resistance correction

Read references/sanity_rules.md before expanding the checker or interpreting a borderline warning. Read references/web_evidence.md before making web-informed trait comparisons. Use references/pft_case_notes.md for retained project evidence and interpretation caveats for previously studied PFT/site combinations.

Web-Informed Evidence

The script does not browse by itself. Codex must do the web search, evaluate sources, convert values into EcoSIM units, and provide the evidence as JSON. This keeps the check reproducible and prevents untraceable web-derived warnings.

Use this JSON shape:

{
  "plants": [
    {
      "pft_code": "woat35",
      "nz": 3,
      "ny": 1,
      "nx": 1,
      "taxon": "Avena fatua",
      "numeric_ranges": [
        {
          "variable": "RUBP",
          "min": 0.05,
          "max": 0.35,
          "unit": "gC rubisco gC protein-1",
          "source": "literature-derived protein-allocation range",
          "url": "https://example.org/source",
          "evidence_level": "species",
          "conversion_note": "Range must match EcoSIM's total-leaf-protein basis."
        }
      ],
      "categorical_expectations": [
        {
          "variable": "ICTYP",
          "contains": "C3",
          "source": "USDA/NRCS or species profile",
          "url": "https://example.org/source",
          "evidence_level": "species"
        }
      ]
    }
  ]
}

Web evidence findings default to WARN because literature and trait database ranges vary with species, site, phenology, and measurement protocol. Use severity: "ERROR" in the evidence JSON only when a value is unequivocally impossible or contradicts a required categorical identity. The IWTYP=0 annual-evergreen convention applies to annual crop plants seeded by humans. It does not apply universally to self-seeding annual grassland or legumes. ISTYP controls annual/perennial life cycle separately from IWTYP, which selects climate-responsive phenology. For self-seeding annuals, select IWTYP according to the site's climate and the active reader/process implementation; drought-deciduous IWTYP=2 is supported. See PlantPhenolMod.F90 near CropPhenoChk and the explicit annual drought-deciduous branches. Do not classify management context from the PFT name alone: clva can represent a natural annual clover. A .desc file alone cannot establish human seeding; record verified crop context in the site evidence and use an explicit categorical IWTYP expectation when applicable. Do not change natural annuals to evergreen merely to silence a checker warning.

For photosynthetic-property checks, interpret RUBP, PEPC, and CHL as fractions of the same total leaf-protein pool. Derive that pool from the smaller of the N- and P-supported amounts in active leaf structural biomass. All leaf structure is active; all non-tree root structure is active; for trees, apply root protein relationships only to active structural root biomass and exclude lignified heartwood. Separate CNRTLIG and CPRTLIG trait inputs are not required. Check SLA1 only as an independently evidenced morphological trait. Do not use SLA1 to back-calculate leaf-area Vcmax, Jmax, or other photosynthetic capacities unless the model mapping and all required conversions are explicitly supported.

Interpret RVSR as the literal arithmetic mean lumen radius of root water conduits: tracheids for conifers and vessel elements for angiosperms. Do not use an effective hydraulic radius or tune RVSR to absorb pit and end-wall resistance; use ARSRA for that correction. Convert published conduit diameters to radius in meters before adding web evidence.

Always report RRAD2M, RVSR, the implied conduit count and the maximum vessel radius for at least one conduit, including when the geometry passes. The 20% lumen fraction and equal-conduit representation are model assumptions, not universal anatomy. Passing this bound does not validate the count or radii; review them jointly against the represented root class. See Root Conduit Hydraulics for the worked check. Do not automatically adjust either radius or impose a universal vessel-count range.

Interpret RSRR as radial root resistivity per unit root surface area in MPa h m-1, not as conductivity. Convert it to the fully wetted intrinsic radial conductivity with k_radial = 1/(3600*RSRR) in m s-1 MPa-1. High RSRR means low radial conductivity. Review it separately from RVSR and ARSRA, which control axial transport, and remember that EcoSIM further increases radial resistance as the soil micropore water fraction declines.

Treat every root-resistance equation and parameter interpretation as EcoSIM-code-version dependent. Before diagnosing or transferring RSRR, RVSR, or ARSRA, verify the active model revision and record its commit or version when available. Recheck radial-resistance assembly, soil-moisture modifiers, conduit-count geometry, and axial-resistance scaling in that revision; the formulas documented here describe the inspected implementation and are not guaranteed across versions.

Literature-Backed Corrections

When the run-folder workflow asks for corrections (create_site_smoke_run.py), scripts/trait_corrections.py plans and applies them; use it rather than editing values by hand. Severe findings (every ERROR, values outside a web-evidence range, wrong categorical codes) are corrected; the Jmax:Vcmax diagnostic is not. Parameter values must be backed by literature: each numeric correction takes the midpoint of a sourced range in the web-evidence JSON (SLA1: 0.25 x that typical value), Rubisco kinetics are corrected through VOMX from a sourced derived_ranges entry RUBISCO_SPECIFICITY, and categorical codes follow ElmIDMod.F90. Exception: C3 tree CHL default (user rule, 2026-10-12): for C3 trees (ICTYP C3 with a tree pfts_short: ndlf, ndld, bdlf, bdln, bdlw, bspr, dfir, jpin, lpin, tasp, woak), when the literature search finds no usable light-harvesting fraction, set CHL = 0.12. This user-authorized default is distinct from literature evidence: record it as user default, not as literature, in the correction log and report. Because Jmax scales with ETMX*CHL, check the protein-normalized Jmax:Vcmax diagnostic after applying it and report the change in Jmax (for the bdlf42 template, 0.025 -> 0.12 raises Jmax 4.8x, Jmax:Vcmax 0.51 -> 2.47). A sourced CHL/ETMX pair replaces the default when one is found. Otherwise, without a sourced range a finding stays unresolved. Corrections go to a site PFT-parameter copy via ParEditor, never to the .desc file, and every correction record carries its citation.

Parser Notes

The parser treats each block header as a plant identity record:

PLANT traits for FUNCTIONAL TYPE (NZ,NY,NX)= <NZ> <NY> <NX> <pft_code>

Parameter names are not globally unique, so preserve file order and section context when discussing findings.

Trait descriptions sometimes contain colons, such as Leaf length:width ratio; split parameter values at the final colon in a row.

Output Options

Use Markdown output for human review:

python3 .agents/skills/ecosim-plant-trait-sanity-check/scripts/check_plant_trait_desc.py /absolute/path/to/plant_trait.1930.desc

Enforce physiological consistency for calibration and run readiness. The model-formulation-sensitive Jmax:Vcmax diagnostic remains a warning:

python3 .agents/skills/ecosim-plant-trait-sanity-check/scripts/check_plant_trait_desc.py /absolute/path/to/plant_trait.1930.desc --strict-physiology

Use JSON output for automated pipelines:

python3 .agents/skills/ecosim-plant-trait-sanity-check/scripts/check_plant_trait_desc.py /absolute/path/to/plant_trait.1930.desc --json

Use web evidence in either Markdown or JSON mode:

python3 .agents/skills/ecosim-plant-trait-sanity-check/scripts/check_plant_trait_desc.py /absolute/path/to/plant_trait.1930.desc --web-evidence /absolute/path/to/web_evidence.json --json

The script returns a nonzero status when ERROR findings are present or when no blocks match the requested grid. With --strict-physiology, physiological-consistency warnings are promoted to ERROR except the model-formulation-sensitive Jmax:Vcmax diagnostic. With --require-class-evidence, unresolved or contradicted class validation is also an error. JSON and Markdown report each class item's model validity, evidence support and overall verdict separately.

Reporting Guidance

For seasonal physiology, realized traits, history-based diagnosis or parameter sensitivity comparisons, use ecosim-plant-history-evaluation. This checker supplies the static parameter checks for that evaluation.

For iterative correction of an existing case through five-day runs and fresh trait read-back, use ecosim-trait-correction-short-run. That workflow uses this checker and the PFT editor; history analysis is disabled by default.

Never edit the trait file. This skill is a diagnostic pass. Report recommended corrections and, when the user asks to apply them, update the corresponding ecosim_pftpar_*.nc file through the ecosim-pftpar-editor skill and ParamEditor.py.

When summarizing results, make clear that the check is scoped to the first grid by default, not the full file. If repeated grid columns exist, say how many total blocks were present and how many first-grid plant blocks were inspected.

Always report each checked plant's RSRR and implied fully wetted k_radial, even when the value passes the deterministic screen. For a high RSRR warning, recommend a sensitivity test and diagnose whether radial resistance dominates total root resistance during moist periods before proposing an edit.

For root-hydraulic findings, report the EcoSIM source version or commit used to verify the equations. If the source revision is unavailable, label equation-level conclusions as version-unverified.

When trait plausibility is being inferred from EcoSIM output, condition GPP, LAI, height, biomass, and mortality judgments on cohort age and initialization. A cohort emerging from seed in the simulation must be compared with seedlings or young stands, not the mature AmeriFlux stand observed at the same location. Treat WTSTDI as an initial-condition pool tied to the simulation start date and disturbance history, not as an intrinsic PFT trait.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall