name: sync-taxonomy
description: Use when the user edits the conflation taxonomy CSVs, or when the frontend filters / taxonomy reference page are suspected to be out of sync with the CSVs. Triggers: "sync taxonomy to the site", "update frontend after taxonomy change", "rebuild taxonomy.html", "check taxonomy drift", "constants.js out of sync", "regenerate taxonomy generated file".
Sync taxonomy to the frontend
The conflation CSVs in src/openpois/conflation/data/ are the single source of truth for three frontend artifacts:
- site/src/taxonomy.generated.js — machine-readable
SHARED_LABELS, OSM_KEYS, OVERTURE_L0S (gitignored; imported by constants.js).
- site/public/taxonomy.html — user-facing taxonomy reference page (gitignored).
- site/src/constants.js — display-label maps
OSM_KEY_LABELS / OVERTURE_L0_LABELS (hand-maintained).
When the CSVs change, (1) and (2) must be regenerated, and (3) must be audited for any new keys/L0s that need human-readable labels.
Steps
-
Check for drift:
python scripts/check_taxonomy_sync.py
Exit 0 = clean, skip the rest. Exit 1 = proceed.
-
Regenerate the generated artifacts:
python scripts/build_taxonomy.py
Writes both site/public/taxonomy.html and site/src/taxonomy.generated.js.
-
Re-run the check:
python scripts/check_taxonomy_sync.py
Must exit 0 now. If it still fails, something is wrong with build_taxonomy.py — debug before continuing.
-
Audit display labels — the check prints WARN: lines if constants.js is missing entries in OSM_KEY_LABELS or OVERTURE_L0_LABELS. Add pretty labels for any new keys (e.g. tourism: 'Tourism'). Missing entries fall back to the raw key (e.g. tourism), which is ugly but not broken.
-
Run the test:
pytest tests/test_taxonomy_sync.py
-
Preview in a browser:
cd site && npm run dev
Verify in each source view:
- OSM: filter checkboxes match
OSM_KEYS in the generated file; toggling a new key (e.g. tourism) filters POIs appropriately.
- Overture: POIs from all 12 L0 categories render (lodging, education, etc.). If a new L0 appears, confirm it's enabled on initial load.
- Conflated: all
SHARED_LABELS appear as checkboxes; any new "Other *" labels are unchecked by default.
/taxonomy.html page renders with the new rows.
-
Build:
cd site && npm run build
Must succeed without new warnings.
Key files
When this skill runs automatically
This is step 1 of skills/update-site — anytime the site is bumped to new data, taxonomy drift is caught first. It is also referenced from skills/conflate-snapshots.
