| name | review-ingredients |
| description | Use this skill to quality-check ontology-mapped MediaIngredientMech ingredient records — verify CHEBI/FOODON/ENVO terms exist and labels match (OAK), enrich chemical properties and synonyms (OLS/OWL), and catch dual-identifier, purity-merge, and kg-microbe-dictionary disagreements. Use after a curation batch, before a KG export, or for periodic maintenance. Issues are graded P1 (blocking) → P4 (optional); P3/P4 can be auto-corrected. |
| version | 1.1.0 |
| tags | ["validation","quality-assurance","ontology","oak","ols","owl","chebi","foodon","envo"] |
| author | MediaIngredientMech Team |
| created | "2026-03-15T00:00:00.000Z" |
Review Ingredients Skill
Overview
The Review Ingredients skill provides quality assurance for ontology-mapped
ingredients in MediaIngredientMech. It verifies that:
- Ontology mappings are correct — term exists, label matches, definition appropriate
- Identifiers are valid — proper CURIE format, dual identifier system consistency
- Synonyms are accurate — chemical variants preserved, no duplicates
- Chemical properties are enriched — SMILES, InChI, molecular formulas populated
- Merge integrity is maintained — purity-aware merge rules followed
Technology stack: OAK (term existence/metadata in CHEBI/FOODON/ENVO), EBI OLS v4
API (formulas, SMILES, InChI, definitions), local OWL files (offline validation +
reasoning), LinkML (YAML structure/constraints).
Dataset: ~1,102 ingredients; ~1,034 mapped (93.8%), ~68 intentionally unmappable.
When to Use This Skill
| Scenario | Workflow | Priority |
|---|
| Post-curation QA | Validate newly mapped ingredients before committing | High |
| Batch validation | Review all mapped ingredients | High |
| Pre-export check | Ensure KG export quality before KG-Microbe ingestion | Critical |
| Periodic maintenance | Monthly validation after CultureMech updates | Medium |
| Synonym verification | Cross-check synonyms with ontology data | Medium |
| Chemical enrichment | Populate SMILES, InChI, formulas from OLS | Low |
| Duplicate detection | Find potential merge candidates | Low |
IF newly mapped batch → interactive review
IF full dataset check → batch review
IF enrichment needed → auto-correct (P3/P4)
IF critical errors → batch review with P1 filter
IF synonym issues → validate_synonyms.py
Review Workflows
1. Interactive Review (single ingredient)
Verify a specific ingredient after manual curation.
PYTHONPATH=src python scripts/review_ingredient.py "sodium chloride"
PYTHONPATH=src python scripts/review_ingredient.py --id CHEBI:26710
PYTHONPATH=src python scripts/review_ingredient.py "glucose" --suggest-fixes
Output: Rich panel with current mapping, P1–P4 validation results, suggested
corrections (apply/skip), and an ontology-metadata comparison.
2. Batch Review (all ingredients)
Validate the whole dataset and generate reports.
PYTHONPATH=src python scripts/batch_review.py \
--output reports/validation_$(date +%Y%m%d) --format md,json,html --threads 4
PYTHONPATH=src python scripts/batch_review.py --priority P1,P2
PYTHONPATH=src python scripts/batch_review.py --source CHEBI
PYTHONPATH=src python scripts/batch_review.py --limit 10 --dry-run
Output: validation_report.md, validation_data.json, dashboard.html. See
reference/api-reference.md for the report formats.
3. Automated Correction (P3/P4 safe issues)
Auto-fix issues that don't require human review.
PYTHONPATH=src python scripts/auto_correct.py --dry-run
PYTHONPATH=src python scripts/auto_correct.py --apply
PYTHONPATH=src python scripts/auto_correct.py --apply --types chemical_properties
PYTHONPATH=src python scripts/auto_correct.py --apply --types synonyms
Safe (auto-applied): enrich chemical properties from OLS, add ontology synonyms,
normalize CURIE formats, fix label whitespace/case.
Unsafe (manual review): change ontology ID, modify preferred_term, merge duplicates,
change mapping quality level.
4. Claude Code-Assisted Review
/review-ingredients
/review-ingredients "calcium chloride dihydrate"
Claude loads the YAML record, runs validation via IngredientReviewer, explains issues
in plain language, proposes corrections with rationale, applies on approval, and updates
curation_history.
Validation Rules
Issues are graded by priority. Full definitions (checks, impact, fix, data sources,
known false-positive patterns) live in
reference/validation-rules.md.
| Level | Meaning | Action | Target |
|---|
| P1 | Critical errors blocking KG export | Fix immediately | 0 |
| P2 | High-priority warnings needing review | Manual review | < 5% |
| P3 | Medium-priority enrichment opportunities | Auto-correct when possible | < 20% |
| P4 | Low-priority info/suggestions | Optional | Any |
| Rule | Summary |
|---|
| P1.1 | Ontology term does not exist (404 from OAK/OLS) |
| P1.2 | Invalid CURIE format (e.g. CHEBI123 not CHEBI:123) |
| P1.3 | Dual identifier mismatch (id vs identifier/ontology ID) |
| P1.4 | Missing required fields (ontology_id, preferred_term) |
| P2.1 | Label mismatch (ontology label vs preferred_term) |
| P2.2 | Definition mismatch (semantic) |
| P2.3 | Deprecated/obsolete ontology term |
| P2.4 | Purity merge violation (pure/impure merged incorrectly) |
| P2.5 | kg-microbe unified-dictionary disagreement on a CHEBI mapping |
| P3.1 | Missing chemical properties (SMILES/InChI/formula) |
| P3.2 | Missing synonyms present in the ontology |
| P3.3 | Low-confidence mapping (< 0.7 or PROVISIONAL) |
| P3.4 | Ambiguous quality level (CLOSE_MATCH without purity/catalog note) |
| P4.1 | Additional ontology synonyms available |
| P4.2 | Alternative ontology matches (score > 0.8 elsewhere) |
| P4.3 | Enrichment opportunities (roles, pathways) |
| P4.4 | kg-microbe synonyms this record lacks (enrichment candidates) |
kg-microbe rules (P2.5, P4.4): the unified chemical dictionary has documented
TSV-parse bugs (merged-row pollution, cation/anion contamination). Never treat it as
authoritative — every proposal is human-verified via OAK round-trip. Loader pattern,
guards, and known false positives are in
reference/integrations.md.
Best Practices
DO ✅
- Run batch validation before KG export — no P1 errors propagate; generates an audit trail.
- Use auto-correct for P3/P4 only — properties enrichment and synonym addition are low-risk; review P1/P2 manually.
- Cache OWL files locally — faster, offline-capable, reproducible.
- Track validation history — add validation events to
curation_history; monitor trends.
- Batch process with checkpoints — resume on failure; 4–8 threads; rate-limit API calls (0.5–1 s).
- Verify corrections before applying —
--dry-run first, review the JSON plan, test on a subset.
DON'T ❌
- Don't auto-correct P1/P2 — label mismatches, deprecated terms, and dual-ID issues need judgment.
- Don't skip validation for "trusted" sources — CultureMech imports and expert curations still have errors; ontologies evolve.
- Don't over-enrich — add only synonyms that improve search; avoid IUPAC clutter.
- Don't ignore P2 warnings — they often signal semantic issues or data-integrity loss.
- Don't run a full batch without sampling — test on 10–20 first; check format and performance.
- Don't hardcode API endpoints — use config, support fallbacks, handle version changes.
Reference Files
Deep material is bundled alongside this skill (progressive disclosure — read on demand):
| File | Contents |
|---|
reference/validation-rules.md | Full P1–P4 rule definitions: checks, impact, fixes, data sources, false-positive patterns |
reference/integrations.md | KG-Microbe unified-dictionary integration (loader, guards), OAK lookup patterns, EBI OLS enrichment, OWL file management |
reference/api-reference.md | IngredientReviewer class + supporting dataclasses, and the markdown/JSON/HTML report formats |
reference/scripts.md | The 7 supporting scripts (review_ingredient, batch_review, auto_correct, apply_corrections, download_ontologies, validate_synonyms, enrich_from_ols) with usage and options |
reference/operations.md | Error handling & retry, troubleshooting, worked examples/scenarios, workflow integration points, quality metrics & trends, and the future-enhancements roadmap |
