From 9db690f914363b31495ec229ebe24f170e06b145 Mon Sep 17 00:00:00 2001 From: "marcin p. joachimiak" <4625870+realmarcin@users.noreply.github.com> Date: Wed, 2 Sep 2026 13:30:43 -0700 Subject: [PATCH] Add single-record YAML curation skill --- .claude/skills/curate-yaml-record/SKILL.md | 137 ++++++++++++++++++ .../references/review-checklist.md | 32 ++++ CLAUDE.md | 5 + 3 files changed, 174 insertions(+) create mode 100644 .claude/skills/curate-yaml-record/SKILL.md create mode 100644 .claude/skills/curate-yaml-record/references/review-checklist.md diff --git a/.claude/skills/curate-yaml-record/SKILL.md b/.claude/skills/curate-yaml-record/SKILL.md new file mode 100644 index 00000000..5c47db09 --- /dev/null +++ b/.claude/skills/curate-yaml-record/SKILL.md @@ -0,0 +1,137 @@ +--- +name: curate-yaml-record +description: Review and curate one CommunityMech community, isolate, or reusable taxon YAML record for ecological scope, taxonomy, interactions, cultivation, environment, claim-level evidence, completeness, and resolvable gaps. Use for a named record audit or improvement; do not use for bulk scouting/ingestion or as permission to contact anyone, spend provider credits, or mutate GitHub. +allowed-tools: Bash, Read, Grep, Glob, WebSearch, WebFetch, Edit, Write +metadata: + category: curation + requires_database: false + requires_internet: true + version: 1.0.0 +--- + +# Curate one CommunityMech YAML record + +Produce a defensible community or taxon record and an explicit account of what +is supported, corrected, missing, and genuinely unknown. Search results and raw +research reports are leads; only inspected sources can support a claim. + +## Boundaries + +- Resolve one target under `kb/communities/`, `data/isolates/`, or `kb/taxa/`. + If a name matches several communities, experiments, or taxon records, stop + and disambiguate before editing. +- An audit/review request is read-only. Curate, improve, complete, correct, or + add-evidence requests authorize local edits to the named record and the + smallest necessary history/generated-product paths. +- Do not generalize a strain pair, enrichment, synthetic consortium, or + cultivation experiment into a natural-community claim. +- Never make an external provider call, spend credits, contact authors, or + create/edit a GitHub item or other outbound message without explicit + authorization for that action. +- Preserve unrelated work and use a dedicated branch/worktree for multi-file + changes. +- Never fill an optional field merely for coverage or interpret absence as + evidence of absence. + +## Read before judging the record + +Read the full target plus: + +- `CLAUDE.md`; +- the applicable `MicrobialCommunity` or `CommonTaxon` class and the taxonomy, + interaction, environment, cultivation, evidence, discussion, and history + classes in `src/communitymech/schema/communitymech.yaml`; +- `history/README.md`; +- [references/review-checklist.md](references/review-checklist.md). + +Inspect reusable `kb/taxa/` records, related communities, committed reference +cache entries, and any source data named by the record. Rendered pages and raw +research prose are not independent evidence. + +## Workflow + +### 1. Establish the baseline + +Read the entire YAML. Record its ID, name, category/state/origin, environment, +taxa, interactions, factors, cultivation/growth media, external resources, +datasets, discussions, evidence, and curation history. For a community record: + +```bash +just validate +just validate-strict +just validate-terms +just validate-references-explained +``` + +For `kb/taxa/`, use the dedicated taxon and term gates (`just validate-taxa` +and `just validate-terms-taxa`). A green schema result proves structure, not +ecological or evidentiary correctness. + +### 2. Verify identity, scope, and taxonomy first + +Confirm whether the record represents a natural community, enrichment, +synthetic consortium, isolate inventory, or another defined scope. Verify every +NCBITaxon/GTDB identifier, canonical label, strain designation, reusable taxon +reference, and community membership claim. Preserve source taxonomic names and +reclassification context instead of silently translating uncertain taxa. + +### 3. Review every scientific claim + +For each taxon, ecological interaction, environmental condition, metal, +metabolite, growth medium, cultivation condition, dataset, and causal direction, +verify that the cited source supports the exact participants, strain/taxon +scope, setting, direction, and strength of wording. + +Every curated assertion should carry evidence at the claim it supports. Confirm +stable identifiers and exact snippets against committed abstract, full-text, +or supplement caches. Do not paraphrase a snippet, join non-contiguous text, or +present a database/search assertion as a primary experiment. + +### 4. Assess completeness and resolve supported gaps + +Apply the checklist and use bounded searches for consequential gaps. Prioritize: + +1. wrong community scope or member identity; +2. unsupported or reversed interactions and causal edges; +3. missing strain, experimental, spatial, or environmental context; +4. cultivation/growth claims linked to the wrong community or medium; +5. missing evidence on material composition, function, or outcome claims. + +Do not add a generic discussion for every empty slot. A discussion should name +a concrete uncertainty, what was checked, why it matters, and what source would +resolve it. + +### 5. Write through the guarded path + +Use a narrowly scoped mutator that loads the record, asserts its ID/path, +changes only reviewed nodes, calls +`communitymech.curate.curation_event.record_curation_event` with +`llm_assisted=True`, and writes through +`communitymech.validation.write_validated.write_validated_community`. +For a reusable taxon, pass `target_class="CommonTaxon"`; the default is +`MicrobialCommunity`. + +Use `curator="claude"` when no identity was supplied. Do not attribute agent +judgement to the user and do not append an event if content is unchanged. +Create the required append-only repository history entry with `just +new-history`; never revise an older history record. + +### 6. Verify and report + +Repeat the focused validation and run proportional wider gates: + +```bash +just validate-history +just audit-writers +just qc +git diff --check +git diff -- history src scripts docs +``` + +If a community record changed, regenerate/check committed pages with `just +gen-html` and `just check-docs-current` as required. Re-read the result and +ensure citations, snippets, and history describe the actual diff. + +Report corrections/additions and sources, retained claims checked, unresolved +gaps and bounded searches, target class used, history artifact, and validation +results. CommunityMech has no record-level REVIEWED flag; never invent one. diff --git a/.claude/skills/curate-yaml-record/references/review-checklist.md b/.claude/skills/curate-yaml-record/references/review-checklist.md new file mode 100644 index 00000000..830aa6e3 --- /dev/null +++ b/.claude/skills/curate-yaml-record/references/review-checklist.md @@ -0,0 +1,32 @@ +# CommunityMech record review checklist + +Use this checklist for one `MicrobialCommunity` or `CommonTaxon`; it does not +require every optional field to be populated. + +## Evidence standard + +- An `EvidenceItem` needs a stable reference, `supports`, evidence source, and + exact source snippet. +- Evidence belongs on the narrowest taxon, interaction, environment, or other + assertion it supports. +- An association, co-occurrence, or enrichment does not establish ecological + interaction direction or causality. +- A paper about a related strain or community is not evidence for the target + without an explicit, justified scope relation. +- Record negative searches as bounded “not found” results. + +## Field-by-field audit + +| Area | Verify | Complete enough when | +|---|---|---| +| Identity/scope | ID, name, origin, category, ecological state, and experimental/natural scope agree. | The record denotes one clearly bounded community or reusable taxon. | +| Taxonomy | NCBITaxon/GTDB identity, canonical label, strain, lineage, and reusable-record link agree. | Every member is resolvable or explicitly uncertain without false precision. | +| Composition | Member inclusion, abundance/role wording, sampling state, and source scope match. | Composition does not combine incompatible time points, sites, or treatments. | +| Interactions | Source, target, interaction type, direction, scope, participants, and evidence agree. | Co-occurrence is not upgraded to interaction or causation. | +| Environment | ENVO term/label, modeled setting, parameters, units, and source context agree. | Natural, host-associated, and engineered contexts remain distinct. | +| Cultivation | Medium, ingredient, vessel, temperature, atmosphere, duration, and measured outcome match. | Conditions are attached to the experiment/community that actually used them. | +| Metals/metabolites | Identity, role, direction of exchange, and experimental support agree. | Presence is not treated as function and a measured analyte is not a causal actor without evidence. | +| Causal claims | Nodes exist, edges have the right direction/type, and every edge has evidence. | Mechanistic graphs preserve organism and experimental scope. | +| Datasets/resources | Identifier resolves and relevance is explicit. | The list is not a bibliography dump. | +| Discussions | Each item is a concrete unresolved question or conflict. | Checked sources and a resolution condition are named. | +| Audit | Per-record history and repository history reflect the exact change. | LLM assistance is explicit and prior history remains append-only. | diff --git a/CLAUDE.md b/CLAUDE.md index dc77ab22..1da9b7db 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -132,6 +132,11 @@ corpus has a known evidence-repair backlog (#417). It is not a CI gate. ## Editing a community or taxon record +Use [curate-yaml-record](.claude/skills/curate-yaml-record/SKILL.md) when the +request is to audit or improve one named community, isolate, or reusable taxon +record. It is read-only for review requests and applies the evidence, guarded +write, and append-only history contracts below. + 1. Read the target, schema, and strong neighboring records. 2. Check whether the same taxon should reference a reusable record in `kb/taxa`. 3. Make the smallest source-supported change; preserve experimental context and