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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.7 KB |
| agents/openai.yaml | config | 314 B |
| references/class_information_validation.md | markdown | 7.3 KB |
| references/evidence_coverage.md | markdown | 4.5 KB |
| references/pft_case_notes.md | markdown | 5.6 KB |
| references/sanity_rules.md | markdown | 23.6 KB |
| references/web_evidence.md | markdown | 11.0 KB |
| scripts/check_plant_trait_desc.py | script | 72.5 KB |
| scripts/plant_class_validation.py | script | 13.5 KB |
| scripts/site_vegetation.py | script | 18.2 KB |
| scripts/trait_corrections.py | script | 10.5 KB |
| tests/test_annual_phenology.py | script | 2.2 KB |
| tests/test_class_information.py | script | 9.5 KB |
| tests/test_physiological_parameterization.py | script | 12.9 KB |
| tests/test_root_conduit_hydraulics.py | script | 8.7 KB |
| tests/test_site_vegetation.py | script | 5.4 KB |
| tests/test_soybean_angle_default.py | script | 1.8 KB |
| tests/test_trait_corrections.py | script | 7.0 KB |
SKILL.md
View on GitHub---
name: ecosim-plant-trait-sanity-check
description: 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](references/class_information_validation.md).
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:
```bash
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.
3. Keep the default grid scope unless the user explicitly asks for another grid. The default is equivalent to:
```bash
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
```
4. 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](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](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](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](references/sanity_rules.md).
5. Maintain the mandatory [evidence coverage audit](references/evidence_coverage.md)
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`.
6. Re-run the checker with the evidence file:
```bash
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
```
7. 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.
8. 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](references/sanity_rules.md) before expanding the checker or interpreting a borderline warning. Read [references/web_evidence.md](references/web_evidence.md) before making web-informed trait comparisons. Use [references/pft_case_notes.md](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:
```json
{
"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](references/sanity_rules.md#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:
```text
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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](../ecosim-plant-history-evaluation/SKILL.md).
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](../ecosim-trait-correction-short-run/SKILL.md).
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: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | 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 |