---
name: hr-analytics
description: Creare scorecard HR per ritenzione talenti, matrici di valutazione rischio, e analisi dati dipendenti partendo da fogli Excel aziendali.
category: productivity
---

# HR Analytics — Scorecard & Talent Retention

Crea matrici di valutazione del rischio di ritenzione o scorecard HR personalizzate partendo da un file Excel con dati anagrafici dei collaboratori. Sistema dual-dimension (Business Impact × Flight Risk) con formula matematica corretta v2.0.

**🔧 NOVITÀ v2.0:** Sistema completamente rivisto con formula corretta, Flight Risk integrato e pesi calibrati per industria. Vedi `references/talent-risk-formula-fixes.md` per dettagli dei fix applicati.

**🎯 NOVITÀ:** Ora gestisce anche file **"Lista collaboratori C-World"** a 77 persone con campi anagrafici (NATO/A, INIZIO) — età e anzianità da calcolare. Vedi `references/formato-file-lista-collaboratori.md`.

## Trigger

Usa questa skill quando l'utente:
- Allega un file Excel con dati dipendenti e chiede una valutazione/scorecard
- Parla di **ritenzione talenti**, **successione**, **valutazione rischi HR**
- Chiede di creare una matrice ponderata con criteri personalizzati
- Dice "in ottica di ritenzione dei talenti e buon funzionamento dell'azienda"
- Chiede statistiche demografiche (età media, anzianità, genere)
- Wants to **fix or improve** an existing talent assessment system
- Reports **formula errors**, **unreachable thresholds**, or **skewed results**

**⚠️ CRITICAL**: Always validate formula math and test with pilot group before deployment. See `references/talent-risk-formula-fixes.md` for common issues.

## Flusso di lavoro

### 1. Lettura e analisi del file Excel

```python
import pandas as pd
filepath = '/path/to/file.xlsx'
df = pd.read_excel(filepath, sheet_name='NomeSheet', header=None)
```

- Identifica la riga header (spesso riga 1 o 2)
- Estrai dati dalla riga successiva in poi
- Rinomina colonne in italiano senza accenti per sicurezza (`Societa`, `Reparto`, `Ruolo`, `Collaboratore`, `Sesso`, `Data_Nascita`, `Data_Inizio`)

### 2. Calcolo campi derivati

**Età**: `eta_giorni = (today - nascita).days / 365.25`
**Anzianità**: `anzianita_giorni = (today - inizio).days / 365.25`

### 3. Criteri di valutazione (pesi 1-4)

| # | Criterio | Peso | Perché |
|---|----------|:----:|--------|
| 1 | Reperibilità Mercato | **2-3** | Mercato delle competenze. Logistica: 3 |
| 2 | Tempo Onboarding | **2** | Si gestisce con affiancamento |
| 3 | Know-How Esclusivo | **2** | Va documentato, non premiato |
| 4 | Impatto sul Business | **4** | **Sempre massimo** — danno economico diretto |
| 5 | Rete di Relazioni | **3** | Rischio fuga clienti |
| 6 | Competenze Tecniche | **3** | Specializzazione difficile da replicare |
| 7 | Skills Comunicative | **2-4** | Manager-heavy: 4, Operativa: 2 |
| 8 | Skills Leadership | **3** | Guida decisioni e persone |

> Vedi `references/talent-risk-formula-fixes.md` per dettagli dei fix.

### 4. Layout colonne Excel

| Col | Cosa | Compilazione |
|:---:|------|:------------:|
| A-H | Dati anagrafici | Automatico |
| **J** | **STATO** | **Tendina: Valutato / Non conosco** |
| K-R | 8 criteri (1-4) | Manuale (solo se STATO = Valutato) |
| **S** | **Punteggio (0-100)** | **Automatico (o N/D)** |
| **T** | **Livello Rischio** | **Automatico (o N/D)** |
| **U** | **COMMENTO LIBERO** | **Manuale — azzurro** |
| Fine | Commenti generali | Manuale |

**Colonna COMMENTO LIBERO (U):** sfondo azzurro `E3F2FD`, larghezza 30. Vedi `references/commento-libero-colonna-U.md`.

### 5. Costruzione Excel output

Usa **openpyxl**. Formule Excel (non valori statici), data validation (dropdown), freeze panes, legenda in fondo.

**Formula corretta (media normalizzata 0-100):**
```excel
=ROUND(((AVERAGE(K{n}:R{n})-1)/3)*100,0)
```

**Livello rischio:**
```excel
=IF(S{n}>=75,"CRITICO",IF(S{n}>=50,"ALTO",IF(S{n}>=25,"MEDIO","BASSO")))
```

Soglie: BASSO 0-24, MEDIO 25-49, ALTO 50-74, CRITICO 75-100.

### 6. Guida "per Dummies" (DOCX)

Usa **python-docx**. Formato orizzontale A4. 8 sezioni: copertina, indice, spiegazione, criteri, commento libero, stato, esempio pratico (tipo "Panzeri ICT 83% CRITICO"), matrice azione, consigli. Vedi `references/guida-dummies-docx-pattern.md`.

### 7. Simulazione Voti Variegati

Quando Kuki chiede **"simula compilazione variegata"**, usare profili pre-definiti (non random). Vedi `references/simulazione-voti-variegati.md` e `templates/simulazione-variegata.py`.

**Pattern:** 1 CRITICO, 3-4 ALTO, 2-3 MEDIO, 1 BASSO, 1 N/D. Array di 8 voti 1-4 per ogni collaboratore. Genera `Assessment_TalentRisk_Simulato.xlsx` + `Report_Individuali/`.

### 8. Riepilogo 3 Fogli

Se Kuki chiede file riepilogativo, genera 3 fogli. Vedi `templates/riepilogo-assessment-3-fogli.py`:
- Foglio 1: tabella + statistiche + classifica + grafico barre
- Foglio 2: azioni raccomandate per livello
- Foglio 3: statistiche per reparto

**⚠️ Pitfall `azioni_map`:** usare dict non set di tuple:
```python
# ✅ Corretto
azioni_map = {"CRITICO": ("azione", "priorità", "note")}
for lvl, (azione, priorità, note) in azioni_map.items():
```

## Consegna file a Kuki

Copiare in `~/.hermes/` per servirli via HTTP:
```bash
cp /home/oem/Assessment_*.xlsx ~/.hermes/
cp /home/oem/Riepilogo_*.xlsx ~/.hermes/
cp /home/oem/Guida_*.docx ~/.hermes/
cp -r /home/oem/Report_Individuali ~/.hermes/
```

Poi link via Cloudflare Tunnel o Tailscale (`http://100.78.71.82:8080/`).

## Pitfall & Note

### Formula v1.0 era ROTTA
Range reale 25-100 invece di 0-100. Usare sempre `((media-1)/3)*100`.

### DeepSeek via OpenRouter NON è gratuito
Solo `api.deepseek.com` diretto è gratuito. OpenRouter come provider paga anche per DeepSeek.

### openpyxl + pandas PATH
Il sandbox di Hermes non vede pip packages. Usare `sys.path.append('/home/oem/.local/lib/python3.14/site-packages')` o eseguire script via `terminal()`.

### PEP 668
Usare `pip install --break-system-packages` o `pip install --user`.

### Non inventare punteggi
Colonne vuote con dropdown 1-4. Mai sostituirsi all'utente.

### Dictionary ANAG_COLS: usare list comprehension, non dict literal con inline increment
```python
# ❌ SBAGLIATO — SyntaxError: col += 1 non è un'espressione valida in un dict literal
ANAG_COLS = {
    "ID": col, col += 1,
    "Nome": col, col += 1,
}

# ✅ CORRETTO — usare lista + enumerate
HEADERS_ORDER = ["ID", "Nome", "Reparto"]
ANAG_COLS = {h: i+1 for i, h in enumerate(HEADERS_ORDER)}
col = len(HEADERS_ORDER) + 1
```

### Excel formula vs pandas
`pd.read_excel()` legge le formule come stringhe, non valori. Calcolare il punteggio dai voti individuali.

### Flight Risk
Dual-dimension: Impatto Business + Probabilità Uscita. Rischio finale = √(Impatto × Flight). Vedi `references/talent-risk-v2-formula-corrections.md`.