bioepic-data/ecosim-agent / .agents/skills/ecosim-plant-trait-sanity-check
ecosim-plant-trait-sanity-check
VerifiedRead-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
- Locate the target
plant_trait.*.descfile. If the user gives no path, prefer a local path they recently mentioned, then search underdata/, then under the repository. - 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.
- 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
- For a site run, first extract the site vegetation and site trait measurements (
scripts/site_vegetation.py extract, thensite-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. Forndlf35,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. - 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 runsite_vegetation.py lint. - 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
- Report findings by severity. Lead with
ERRORfindings, thenWARNfindings, and include the plant code, grid tuple, parameter name, source line, and web source when applicable. - 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
CLASSas 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:Vcmaxand a lower-priority, model-formulation-sensitive C3/C4Jmax:Vcmaxdiagnostic - pathway-specific
FCO2, C4 mesophyll chlorophyll partitioning, and PAR/shortwave absorptance - total photosynthetic protein allocation without double-counting the shared leaf-protein pool
SLA1against explicit species- or site-specific web evidence, without using SLA to infer photosynthetic kineticsANGSH = 0for plant forms without petiole or sheath tissue, including conifer, lichen, and moss PFTs- Soybean (
soyb*)ANGSH = 45 degreesfrom horizontal is the user-selected default (2026-11-13). The checker reports other numeric values asuser-defaultwarnings, including in strict physiology mode. Respect explicit sensitivity values; keep.descfiles read-only. This is a parameter preference, not a literature-derived range, a leaf-inclinationCLASSsetting, 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 throughParEditor. - 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 <= PhiMAXand fine-root radius not exceeding primary-root radius RSRRradial root resistivity, its implied fully wetted conductivity, and its interaction with soil drying and total root resistance- literal
RVSRconduit radius, conifer tracheid anatomy, implied conduit countN=0.2*(RRAD2M/RVSR)^2 >= 1(equivalentlyRVSR <= sqrt(0.2)*RRAD2M), andARSRAresistance 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |