| 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.
