location-enrichment

name	location-enrichment
description	Standardize positions.location free-text into structured loc_*/work_*/role_family columns BEFORE marking any position as `checked`. Covers 10 special cases (Europe Remote, Italy+remote, multi-location, US-entity-in-EU). Enforces one-position-at-a-time, peer-aligned vocabulary, never-NULL work_country. Use whenever the Analyst is about to set status=checked on a position.
allowed-tools	Bash(python3 *), Bash(curl *), Bash(jq *), WebSearch

location-enrichment — playbook strutturazione location + role_family

L'Analista popola 11 colonne della tabella positions PRIMA di marcare status=checked. Mai lasciare una position checked senza location enrichment.

Le 11 colonne da popolare

role_family         text   categoria semantica del ruolo
loc_city            text   città di ufficio (NULL se solo country)
loc_region          text   regione/stato (opzionale)
loc_country         text   paese fisico ufficio (NULL se solo continent)
loc_country_code    text   ISO-3166 alpha-2: IT, IE, HU, ...
loc_continent       text   Europe | Asia | Americas | Africa | Oceania
work_mode           text   onsite | hybrid | remote
work_country        text   paese contrattuale (entity che firma) — MAI NULL
work_country_code   text   ISO-2 del work_country
is_multi_location   bool   true se JD elenca più città/paesi
location_notes      text   note libere analista

REGOLE comportamentali (CRITICHE — sim 1-2 ha trovato problemi qui)

R1 — Una posizione alla volta (NO BATCH)

Processa il tuo range una posizione per turno: leggi JD → ragiona → db-update → status=checked → prossima. NIENTE caricare 20+ JD in un unico turno LLM. Eccezione: 3-5 casi banali senza web search (es. "Dublin, Ireland" + hybrid).

Perché: batch da 17k+ tokens (sim 1) genera responses generiche ("multi-location + remote + EU") invece di dati specifici per ogni record. E gli altri analisti girano a vuoto durante il tuo mega-turn.

R2 — Peer DB lookup tassonomia (ogni 5-10 record)

PRIMA di scegliere un valore role_family, controlla cosa hanno usato i colleghi:

python3 /app/shared/skills/db_query.py raw \
  "SELECT role_family, COUNT(*) AS n FROM positions
   WHERE role_family IS NOT NULL
   GROUP BY role_family ORDER BY n DESC"

Se trovi una family semanticamente equivalente, ALLINEATI al loro nome. Esempi sbagliati visti in sim 1:

✗ "Translation / Localization" vs "Localization / Language Quality"
  vs "Language / Localization"           → uno solo
✗ "Customer Support" vs "Customer Success / Technical"
  vs "Technical Support"                 → uno solo
✗ "Technical Engineering" per un Technical Writer  → wrong

Se la posizione è davvero una nuova categoria, annota in location_notes perché.

R3 — Fallback work_country (MAI NULL su checked)

Se dopo 2 tentativi di web search non trovi work_country con certezza, NON lasciarlo NULL. Procedi:

1. Paese del posting board (es. linkedin.it → IT) + nota "work_country inferred from posting board (low confidence)"
2. Paese citato in JD come "region" / "office" anche se non sede legale
3. Ultima istanza: il loc_continent come placeholder + nota "work_country=Europe placeholder, entity unverified"

R4 — Peer DB lookup città (PRIMA di scrivere loc_city)

Esattamente come R2 per role_family, ma per le città. PRIMA di scrivere loc_city, controlla quale forma i colleghi hanno già usato per quel paese, così non crei un duplicato in altra lingua (Rome vs Roma, Milan vs Milano):

python3 /app/shared/skills/db_query.py raw \
  "SELECT loc_country, loc_city, COUNT(*) AS n FROM positions
   WHERE loc_city IS NOT NULL
   GROUP BY loc_country, loc_city ORDER BY loc_country, n DESC"

• Se la città è già presente in una forma → ALLINEATI a quella (purché rispetti lo standard "esonimo inglese", vedi sotto).
• Se vedi un duplicato in lingua diversa già nel DB (es. esiste sia Roma sia Rome), usa la forma inglese e annota in location_notes la forma da consolidare.

Standard di scrittura

Paesi (loc_country / work_country)

Sì ✓	No ✗
Italy	Italia, IT, Italie
United Kingdom	UK, Great Britain, England
Czechia	Czech Republic
Netherlands	Holland, The Netherlands
Székesfehérvár	Szekesfehervar (preserva sempre i diacritici)
ISO-2 IT, IE, HU, NL, DE, GB, US, ES	ISO-3, lowercase

Città (loc_city) — esonimo INGLESE quando esiste

Regola unica: scrivi sempre la forma inglese della città quando esiste un esonimo consolidato. Se la città NON ha un esonimo inglese, usa il nome locale preservando i diacritici. Questo allinea l'Analista alla mappa di dedup dello Scout (_CITY_SYNONYMS in shared/skills/db_insert.py) ed elimina i duplicati Rome/Roma, Milan/Milano.

Sì ✓ (esonimo EN)	No ✗ (forma locale)
Rome	Roma
Milan	Milano
Naples	Napoli
Turin	Torino
Florence	Firenze
Venice	Venezia
Genoa	Genova
Munich	München, Monaco di Baviera
Cologne	Köln
Vienna	Wien
Prague	Praha
Brussels	Bruxelles
Lisbon	Lisboa
Plzeň (no esonimo → locale + diacritici)	Plzen

In dubbio sull'esistenza di un esonimo consolidato, applica il peer DB lookup (R4) e allineati alla forma già presente per quella città.

Casi speciali (decisione standard)

A — "Europe Remote" / "EMEA - Flexible" / "Remote"

loc_city          = NULL
loc_country       = NULL          # niente paese fisico vincolato
loc_continent     = "Europe"      # solo se area è esplicita
work_mode         = "remote"
work_country      = <web search HQ azienda → fallback R3>
is_multi_location = false
location_notes    = "Remote within EU"

B — "Italy" / "Spain" + full_remote (paese + remote)

loc_country       = "Italy"
loc_country_code  = "IT"
loc_continent     = "Europe"
work_mode         = "remote"
work_country      = "Italy"       # stesso paese, contratto IT
work_country_code = "IT"

C — "Dublin, Ireland" + hybrid (city+country pulito)

loc_city          = "Dublin"
loc_region        = "Leinster"    # opzionale
loc_country       = "Ireland"
loc_country_code  = "IE"
loc_continent     = "Europe"
work_mode         = "hybrid"
work_country      = "Ireland"
work_country_code = "IE"

D — Multi-location stesso paese ("Barcelona / Malaga")

loc_city          = NULL
loc_country       = "Spain"
loc_country_code  = "ES"
loc_continent     = "Europe"
work_mode         = "hybrid"
work_country      = "Spain"
is_multi_location = true
location_notes    = "Barcelona or Málaga (candidato sceglie)"

E — Multi-country ("Amsterdam, Berlin, London, Remote-Europe")

loc_city          = NULL
loc_country       = NULL
loc_continent     = "Europe"
work_mode         = "hybrid"      # o remote
work_country      = <HQ azienda via web>
is_multi_location = true
location_notes    = "EU multi-country: NL, DE, GB + remote option"

F — Area metropolitana vaga ("Greater Bologna Metropolitan Area")

loc_city          = "Bologna"     # promuovi alla città principale
loc_country       = "Italy"
location_notes    = "Area metropolitana Bologna (raggio ~30km)"

G — Azienda US con entity EU che assume in Spagna

loc_country       = NULL
loc_continent     = "Europe"
work_mode         = "remote"
work_country      = "Spain"       # entity locale che firma
location_notes    = "US company (X Inc.), assume tramite entity ES"

H — JD precisa città che lo scout aveva generalizzato

Scout aveva scritto "Italy" → JD nel testo specifica "Milano HQ": promuovi a città.

loc_city          = "Milan"
loc_country       = "Italy"
location_notes    = "JD specifica HQ Milano (scout aveva 'Italy')"

I — City abbreviata ("Dublin 2")

loc_city          = "Dublin"
loc_region        = "Dublin 2"    # distretto in region

J — Azienda solo job board (Railsware, Top Remote Talent, ecc.)

Quando l'azienda è una società distribuita senza HQ chiaro: applica fallback R3 (paese del posting board) + annota.

Vietati assoluti

• ❌ loc_country = "Europe" o "EMEA" — è continent, non country
• ❌ Mappare "EMEA" come "Europe" senza controllo (include Middle East + Africa)
• ❌ work_country = NULL su una position checked (rompe UI stipendio)
• ❌ Inventare role_family se i colleghi hanno già usato simili → vedi R2
• ❌ Scrivere loc_city in lingua locale quando esiste l'esonimo inglese (Roma, Milano, Napoli → usa Rome, Milan, Naples) o senza peer DB lookup → vedi R4 + tabella città
• ❌ Caricare il batch intero del proprio range → vedi R1
• ❌ loc_city = "Remote" / "Anywhere" / "Distributed" — NON sono città. Se la position è full-remote senza city specifica, loc_city = NULL. Bug osservato in sim 4: A2 ha scritto loc_city='Remote' per 8 record (Canonical, Miratech, Link Group, ecc.). Correggi sempre con db_update --loc-city "" (stringa vuota = NULL).

Comandi tipo

Salvataggio struttura location completa

python3 /app/shared/skills/db_update.py position <ID> \
  --loc-city "Dublin" \
  --loc-region "Leinster" \
  --loc-country "Ireland" --loc-country-code "IE" \
  --loc-continent "Europe" \
  --work-mode "hybrid" \
  --work-country "Ireland" --work-country-code "IE" \
  --is-multi-location false \
  --role-family "Technical Writing" \
  --location-notes ""

Peer lookup tassonomia (eseguilo ogni 5-10 record)

python3 /app/shared/skills/db_query.py raw \
  "SELECT role_family, COUNT(*) AS n
   FROM positions WHERE role_family IS NOT NULL
   GROUP BY role_family ORDER BY n DESC"

Promozione a checked (SOLO dopo enrichment completo)

python3 /app/shared/skills/db_update.py position <ID> --status checked \
  --notes "ESPERIENZA: ... \\n LINGUA: ... \\n SENIORITY: ..."