| name | siae-service-logic-map |
| description | Use when profiling microservices for documentation OR for impact analysis. Two modes: - **Mode A (build-catalog)**: build L1+L2+L3 catalog (domain profile + workflow
map + business rules) for a cluster of microservices. Trigger: "build catalogo
L1/L2/L3", "lanciamo su <pattern>", "analizziamo <sistema>", "regole business
di X", "Drools in Y", "cosa fa {servizio}", "mappa la logica", "quali servizi
gestiscono X".
- **Mode B (impact-analysis)**: pre-flight MCP single-task con output
standardizzato (rischio + 3 vincoli + volumi). Trigger: "modifica su servizio
business-critical", "impact analysis", "blast radius", "demand impact",
"pre-flight MCP", /forge-mcp-preflight.
Examples: "cosa fa servizio X", "impact di modifica DTO Y", "build catalogo cluster Z".
|
SIAE Service Logic Map — Domain Profile e Workflow Map
╔══════════════════════════════════════════════════════════════════╗
║ ███████╗██╗ █████╗ ███████╗ ██████╗ ███████╗██╗ ██╗ ║
║ ██╔════╝██║██╔══██╗██╔════╝ ██╔══██╗██╔════╝██║ ██║ ║
║ ███████╗██║███████║█████╗ ██║ ██║█████╗ ██║ ██║ ║
║ ╚════██║██║██╔══██║██╔══╝ ██║ ██║██╔══╝ ╚██╗ ██╔╝ ║
║ ███████║██║██║ ██║███████╗ ██████╔╝███████╗ ╚████╔╝ ║
║ ╚══════╝╚═╝╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚══════╝ ╚═══╝ ║
║ 🗂️ DevForge · SIAE Service Logic Map ║
╚══════════════════════════════════════════════════════════════════╝
Tipo: Flexible | Fase SDLC: 1. Init & Setup
Modalita' di invocazione
La skill opera in 2 modalita' distinte. Riconosci la modalita' dal contesto del prompt utente.
A. Build-catalog (default) — vedi Step 0..6
Trigger: "build catalogo", "lanciamo su {pattern}", "mappa la logica".
Output: catalogo L1+L2+L3 multi-cluster in docs/logic-catalog/.
B. Impact-analysis (single-task pre-flight) — vedi Pipeline Pre-flight MCP
Trigger: il task corrente tocca un servizio gia' mappato nel KG sport-kg.
Prefissi servizio (allineati con hooks/sport-task-detect — single source of truth):
sport-*-service, sport-*-drools, sport-gestione-*, pop-*-service, pop-be,
pae-*, ciam-*, dol-be, digital-channels-sport-*, esb-sport-*, esb-sso-*,
mag-concertini-*, portal-apigateway-*, ttpp-*-bff-service. Tipicamente invocata
come Stage 0 prima di brainstorming/debugging, oppure dispatchata all'agent mcp-impact-analyst.
Output: blocco markdown standardizzato ## MCP Pre-flight: <service> — <feature>
copiabile in cima al design doc.
Quale modalità scegliere — Flowchart 3 domande
1. Stai facendo IMPLEMENTAZIONE di una modifica specifica?
├── SI → Mode B (impact-analysis): /forge-mcp-preflight
└── NO → Step 2
2. Stai facendo DOCUMENTAZIONE / onboarding di un sistema?
├── SI → Mode A (build-catalog): "build catalogo L1/L2/L3" o "analizziamo <sistema>"
└── NO → Step 3
3. Stai facendo INVESTIGAZIONE Q&A su come funziona X?
├── SI → NEITHER. Usa siae-debugging o qa-investigator subagent
└── NO → Stop e chiedi all'utente cosa intende
| Modalità | Output | Subagent | When |
|---|
| A. build-catalog | docs/catalog/L1+L2+L3 markdown | siae-service-logic-map.md (forge-logic-build) | Documentation, onboarding nuovo cluster |
| B. impact-analysis | Pre-flight card (rischio + 3 vincoli + volumi) | mcp-impact-analyst | Pre-design di task implementativo |
Pipeline Pre-flight MCP (modalita' B)
Pipeline 5-step deterministica, tool MCP sport-kg richiesti. Esegue questo ordine
quando si invoca la modalita' impact-analysis.
1. disambiguazione servizio → list_services o find_service_for_symbol
2. pre-flight rischio → demand_impact (output: ALTO/MEDIO/BASSO)
3. wide scan parallelo → service_full_context + service_health
+ debug_service + who_calls (parallel)
4. drill-down condizionale → demand_impact_deep se rischio MEDIO/ALTO
5. verifica empirica → impact_with_evidence sull'endpoint contratto
Step 1 e 2 sono sequenziali. Step 3 in parallelo. Step 4-5 condizionali.
Mai saltare Step 2 (gating del rischio).
Output template — REQUIRED FORMAT
Il formato di output canonico è definito in agents/mcp-impact-analyst.md
§Output — REQUIRED FORMAT (v2). Grep-abile per riferimento in design doc
(siae-writing-plans lo include in cima al piano). Sintesi dei campi chiave:
- Rischio + Top 3 vincoli, ciascuno con
Status enum v2 (CONFIRMED | PARTIAL | NOT_FOUND_IN_INDEX | PROVEN_ABSENT_UNDER_SCOPE | REFUTED) e decisione actionable.
- Confidence + Freshness (
observed_at/ttl_hint) + Falsifiable_by da envelope D1.
- Batch jobs / Business rules / External callers M2M / Drift signals (KG↔ES).
Quando l'output va in design doc
Il blocco va in cima al design doc generato da siae-brainstorming (sezione "Contesto"),
prima delle opzioni proposte allo Step 4 di brainstorming. Senza il blocco, le opzioni
sono cieche su latency, error rate, idempotenza, transazionalita', failure coupling.
Limiti tool MCP noti (workaround documentati)
list_services(filter="X") — bug case-sensitive, ritorna 0 anche con match. Usa list_services() full-dump se filter risulta vuoto.who_calls — caller duplicati con confidence diverse, deduplicare per max(score).service_full_context — output verboso (50KB+), preferire dispatch all'agent mcp-impact-analyst per protezione context window.- Endpoint con 0 caller in 30gg ma 100k+ req/24h = traffico esterno (frontend/gateway), non bug nei dati.
change_type=feature con free-text → confidence MEDIUM. Preferire change_type=endpoint o table quando possibile.
Per gap aperti su MCP sport-kg vedi ~/.claude/projects/<project>/memory/mcp_sport_kg_gaps.md.
📊 Dai repo itsiae: Il 56% delle regole business Drools non era documentato da nessuna parte — conoscenza tacita persa al turnover.
Fonte: analisi dei repository GitHub dell'org itsiae.
ANTI-HALLUCINATION PROTOCOL — NON NEGOZIABILE
MAI descrivere cosa fa un servizio senza citare il file sorgente.
SE NON HAI LETTO IL FILE, IL WORKFLOW NON ESISTE.
Confidence Tag Obbligatori
| Tag | Significato |
|---|
[CONFIRMED] | evidenza letta direttamente dal file |
[INFERRED] | dedotto da nome classe/metodo — DEVI citare file:riga |
[UNVERIFIED] | nessuna evidenza — nel Gap Report, MAI rimosso |
[FILE_NOT_FOUND] | file non accessibile — documenta il gap |
Step 0 — SYSTEM_MAP.md: Discovery o Auto-Generate
SYSTEM_MAP.md e' l'input per la cluster detection (Step 3).
Questa skill lo cerca automaticamente — non serve generarlo prima.
SYSTEM_MAP=""
for CANDIDATE in \
"docs/SYSTEM_MAP.md" \
"docs/systems/"*"/SYSTEM_MAP.md" \
/tmp/siae-sysmap-*/SYSTEM_MAP.md; do
FOUND=$(ls $CANDIDATE 2>/dev/null | sort | tail -1)
if [ -n "$FOUND" ]; then
SYSTEM_MAP="$FOUND"
echo "[FOUND] SYSTEM_MAP.md: $SYSTEM_MAP"
break
fi
done
Se trovato: usa il file trovato → procedi al Step 1.
Se non trovato: genera automaticamente eseguendo siae-microservices-map
sul pattern di repo specificato dall'utente, poi riprendi da Step 3.
REQUIRED SUB-SKILL: siae-microservices-map
Non chiedere all'utente di eseguire un comando separato.
Cerca SYSTEM_MAP.md in questo ordine:
docs/SYSTEM_MAP.md (output standard di siae-microservices-map)- Se non trovato: invoca
siae-microservices-map per generarlo
Quando si Applica
Sempre:
- Onboarding su servizio sconosciuto: "cosa fa sport-X?"
- Impact analysis cross-repo: "quali servizi gestiscono Y?"
- Build catalogo logic per cluster: dispatch skill
siae-service-logic-map direttamente (modalità A)
- Ricerca concetti/workflow: trigger sentence "cerca workflow di X" o "quali servizi gestiscono Y"
Output: un documento per cluster (non per singolo servizio) che descrive
il dominio funzionale e i workflow di tutti i servizi del cluster.
Step 1 — PRE-FLIGHT: Verifica Accesso GitHub
Prima di procedere, verifica che l'accesso ai repo sia disponibile.
gh auth status
gh api /orgs/itsiae --jq '.login'
gh repo list itsiae --limit 20 --json name,isPrivate --jq '.[] | [.name, .isPrivate] | @csv'
🟢 SICURO — Nessuna pre-flight card necessaria.
Se l'accesso e' negato:
- Verifica le credenziali con
gh auth login
- Se persiste, documenta i repo non accessibili come
[FILE_NOT_FOUND]
- NON procedere assumendo l'accesso
Step 2 — ENUMERATE: Inventario Repo
Identifica i repo target per il dominio richiesto.
2a — Disambiguazione Pattern (se l'utente usa un nome semantico)
Se l'utente usa un nome semantico (es. "filiera del credito") invece di un prefisso tecnico,
prova SEMPRE almeno 3 varianti (nome esteso, acronimo, abbreviazione) con gh repo list prima
di dichiarare "nessun repo trovato". Mostra i candidati trovati e chiedi conferma.
2b — Fetch Lista Confermata
gh repo list itsiae --limit 500 --json name --jq '[.[] | .name | select(test("{pattern}"))]'
gh api /repos/itsiae/{repo}/branches --jq '[.[].name]'
Output atteso: lista ordinata di {org}/{repo} confermata dall'utente.
Gap Report — repo non accessibili:
[FILE_NOT_FOUND] itsiae/{repo}: accesso negato o repo non esistente
Step 3 — CLUSTER DETECTION
Legge docs/SYSTEM_MAP.md ed estrae i cluster dal grafo delle dipendenze.
🟢 SICURO — Nessuna pre-flight card necessaria.
3a — Estrai il Grafo
cat docs/SYSTEM_MAP.md
Analizza il blocco PlantUML in SYSTEM_MAP.md:
- Estrai le edge
A --> B (dipendenze dirette tra servizi)
- Raggruppa per connettivita': servizi con dipendenze reciproche o path condivisi = stesso cluster
- Servizi isolati (nessuna edge) = cluster singleton
Regola di evidenza: usa SOLO le dipendenze documentate in SYSTEM_MAP.md.
MAI inferire cluster dal nome del servizio o dal dominio percepito.
3b — Proponi Cluster all'Utente
Presenta i cluster proposti (nome, servizi, evidenza SYSTEM_MAP.md) e chiedi conferma.
🟡 MEDIO -- Attendere conferma utente prima di procedere al Step 4.
Se l'utente modifica i cluster, documenta la modifica come [INFERRED] in clusters.yaml.
Step 4 — BUILD CATALOG
4a — Setup Output Directory
OUTPUT_DIR="docs/logic-catalog"
mkdir -p "$OUTPUT_DIR"
echo "Logic catalog dir: $OUTPUT_DIR"
4b — Pre-fetch Dati per Cluster (Parent via Bash)
Vedi TEMPLATES.md sezione "Pre-fetch Dati per Cluster" per i comandi di pre-fetch completi.
Regola critica: il parent pre-fetcha SEMPRE via Bash. Gli agenti ricevono i dati inline — non hanno permesso di usare Bash autonomamente.
4c — Pilot Test (OBBLIGATORIO su sistemi con 3+ cluster)
| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-service-logic-map |
|---|
🔬 Pilot test: 1 cluster su N totali · 📦 Dati pre-fetchati: Service.java + Entity.java + openapi |
| ▼ Azioni |
1. 🤖 Dispatch 1 agente pilot (cluster piu piccolo) → docs/logic-catalog/ |
2. 📄 Scrittura 1 file cluster → docs/logic-catalog/cluster-{nome}.md |
| 💡 Perche': Validazione pipeline prima del full run |
| 🚫 Se NO: Pilot annullato, full run non garantito senza validazione |
Procedura pilot:
- Pre-fetcha dati per il cluster piu' piccolo (meno repo)
- Dispatcha 1 agente con dati inline nel prompt
- Verifica:
ls docs/logic-catalog/cluster-*.md | wc -l deve essere 1
- Se OK → Step 4d. Se file mancante → STOP, diagnostica.
4d — Dispatch Agenti per Cluster (Full Run)
| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-service-logic-map |
|---|
🤖 Agenti: K agenti (1 per cluster) in parallelo · 📦 Cluster: lista cluster confermati al Step 3 · ✅ Pilot: 1/1 file verificato |
| ▼ Azioni |
1. ⚡ Dispatch tutti gli agenti in parallelo → docs/logic-catalog/ |
2. 📄 Scrittura K file cluster → docs/logic-catalog/cluster-*.md |
| 💡 Perche': Pilot OK, full run pronto |
| 🚫 Se NO: Full run annullato, catalogo parziale |
Dispatcha TUTTI i cluster in un blocco parallelo (1 agente per cluster).
Vedi TEMPLATES.md sezione "Istruzione Critica Agenti" per il testo da includere verbatim in ogni agente.
4e — Genera clusters.yaml (Parent)
Dopo che tutti gli agenti hanno scritto i file cluster, il parent genera il file indice:
ls docs/logic-catalog/cluster-*.md | wc -l
Il parent scrive docs/logic-catalog/clusters.yaml e docs/logic-catalog/system-overview.md.
Vedi TEMPLATES.md sezione "Template clusters.yaml" per il formato esatto.
4f — Collect: Verifica File Scritti
ls docs/logic-catalog/cluster-*.md | wc -l
ls docs/logic-catalog/clusters.yaml
ls docs/logic-catalog/system-overview.md
Se mancano file → re-dispatcha solo i cluster mancanti (non tutto il batch).
Step 5 — POST-BUILD: Documentazione Formale
| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-service-logic-map |
|---|
📚 Input: docs/logic-catalog/cluster-*.md + clusters.yaml · 🏗️ Scope: Documentazione formale catalogo L1+L2+L3 |
| ▼ Azioni |
1. 📄 Esecuzione siae-documentation su cluster generati → docs/logic-catalog/ |
| 💡 Perche': POST-BUILD obbligatorio — genera doc navigabile dal team |
| 🚫 Se NO: Il catalogo resta senza documentazione formale |
Dopo COLLECT (Step 4f), eseguire automaticamente siae-documentation
sui cluster-*.md generati. Non proporre — eseguire.
REQUIRED SUB-SKILL: siae-documentation
Input: docs/logic-catalog/cluster-*.md + clusters.yaml + system-overview.md
Scope: documentazione tecnica del sistema (API guide per cluster, ADR, enriched overview)
Il sistema di documentazione riceve il catalogo L1+L2+L3 come input e produce
documentazione formale navigabile da altri developer del team.
Step 6 — QUERY (forge-logic-search)
Riceve keyword dall'utente, cerca nel catalogo locale.
grep -ri "{keyword}" docs/logic-catalog/ --include="*.md" -l
grep -ri "{keyword}" docs/logic-catalog/clusters.yaml
grep -ri "{keyword}" docs/logic-catalog/{file} -B2 -A2
Output atteso: tabella con colonne cluster | servizio | layer | campo | valore | source.
Vedi TEMPLATES.md sezione "Esempio Query Output" per un esempio completo.
Template e Esempi Output
Vedi TEMPLATES.md per template completi L1/L2/L3 e esempi output.
Limiti Operativi
| Vincolo | Limite | Se superato |
|---|
| Tentativi fix per errore | 2 | Fermati. Diagnosi diversa necessaria. |
| File modificati per singolo step | 5 | Se devi toccare piu' file, decomponi in sub-task. |
| Output max per raccomandazione | 200 righe | Prioritizza. Top 5 issue, non lista esaustiva. |
Tabella Anti-Razionalizzazione
| Pensiero | Realta' |
|---|
| "Dal nome del metodo capisco cosa fa" | Il nome non e' evidenza. Leggi la firma. |
| "Questo servizio probabilmente gestisce X" | Probabilmente = allucinazione. Leggi il file. |
| "I workflow si capiscono dal dominio" | Solo firme @Service con source:riga sono evidenza. |
| "Ho gia' visto servizi simili" | Ogni repo e' diverso. Analizza questo specifico. |
| "Non trovo il Service.java, ma fa sicuramente X" | [FILE_NOT_FOUND]. Documenta il gap. |
| "Il pilot e' lento, salto al full run" | Senza pilot, non sai se gli agenti scrivono i file. |
| "I cluster si capiscono dal nome dei servizi" | Solo edge in SYSTEM_MAP.md sono evidenza. |
| "Questo cluster mi sembra ovvio" | Ovvio non e' CONFIRMED. Leggi SYSTEM_MAP.md. |
| "Salto la conferma cluster, e' chiaro" | La conferma protegge da cluster sbagliati nel catalogo. |
Classificazione Rischio Operazioni
| Operazione | Livello | Card |
|---|
Verifica accesso GitHub (gh auth status) | 🟢 Sicuro | No |
Enumerate repo (gh repo list) | 🟢 Sicuro | No |
| Lettura SYSTEM_MAP.md + estrazione cluster | 🟢 Sicuro | No |
| Proposta cluster all'utente | 🟢 Sicuro | No |
| Pre-fetch file via Bash (parent) | 🟢 Sicuro | No |
| Pilot test — dispatch 1 agente | 🟡 Medio | Si |
| Full run — dispatch K agenti in parallelo | 🟡 Medio | Si |
Query catalogo locale (grep) | 🟢 Sicuro | No |
Scrittura docs/logic-catalog/ | 🟡 Medio | Si |
| POST-BUILD siae-documentation | 🟡 Medio | Si (nella skill siae-documentation) |
Vincoli Non Negoziabili
- MAI procedere senza
docs/SYSTEM_MAP.md — prerequisito assoluto
- MAI assegnare un servizio a un cluster senza evidenza da SYSTEM_MAP.md
- MAI descrivere workflow senza firma metodo reale con
source:riga
- MAI inferire entita' dal nome del servizio — solo
@Entity class names
- SEMPRE conferma utente sui cluster prima del build (Step 3b)
- SEMPRE Gap Report per ogni repo, anche se vuoto
- SEMPRE pilot test con 1 cluster prima del full run (su sistemi con 3+ cluster)
- Gli agenti usano SOLO Write tool — il parent pre-fetcha i dati via Bash
- I Confidence Tag sono obbligatori su ogni voce del catalogo
REQUIRED SUB-SKILL: siae-verification
Prima di dichiarare il build del catalogo completato, invoca siae-verification
con evidenza: ls docs/logic-catalog/cluster-*.md | wc -l deve corrispondere
al numero di cluster confermati al Step 3b.
