# Motore finding — schema e PCB (stesso oggetto)

Fonte: specifica di Michele (Project chat). Vale per **analizzatore schematico e PCB**. Un finding è un oggetto riproducibile, non un paragrafo LLM.

Libreria datasheet: **una** (`library/extracted` + extracted/ di progetto). L’esame PDF profondo gira **una volta** (pipeline schema). Il job PCB consuma quella cache e aggiunge solo geometria.

---

## 1. Tre strati — non mescolare

Ogni finding ha **tre campi distinti**:

| Strato | Nome campo | Chi lo produce | Cosa può contenere |
| --- | --- | --- | --- |
| **FACT** | `facts` | Motore deterministico (netlist, BOM, `.kicad_pcb`) | Solo osservabili: pin, net, mm, V, A, width, thickness |
| **REQUIREMENT** | `requirement` | Rule DB + estrazione libreria (citazione, pagina, MPN) | Testo **sourced**. Provenance nel DB, non nella prosa del modello |
| **INFERENCE** | `inference` | Ingegnere / LLM **solo** qui | Giudizio. Mai copiare un’inferenza in `facts` o `requirement` |

Non mescolare: un check non scrive “probabilmente sottodimensionato” dentro `facts`. Se manca un parametro, `evidence_status=INSUFFICIENT` e si **dice** che manca — non si inventa 1 oz, 10 °C, 50 Ω, IEC.

`finding` / `why` restano per compatibilità UI (copia di facts / requirement).

---

## 2. Provenance datasheet (rule DB)

Sul **record di regola**, non nel testo LLM:

| `provenance` | Significato | Classe / severity |
| --- | --- | --- |
| **MANDATORY** | Shall / abs-max / pin NC | Può essere **RULE** + ERROR |
| **RECOMMENDED** | Should / layout note | **Mai ERROR**. RISK o INFO |
| **TYPICAL** | Typical / default application | INFO o RISK, mai RULE ERROR |
| **EXAMPLE** | Figure / typical application circuit | REVIEW o INFO |

**Recommended ≠ ERROR.** Il clamp è nel motore (`complete_finding`).

---

## 3. Classi — Design Rule ≠ Design Review

| `finding_class` | Ruolo |
| --- | --- | --- |
| **RULE** | Violazione di un requisito MANDATORY misurato (FACT vs REQUIREMENT). Deterministico. |
| **RISK** | Margine / derating / inferenza ingegneristica con evidenza parziale. |
| **REVIEW** | Esame AI (schema o PCB). Non è una design rule. |
| **INFO** | Inventario, evidenza insufficiente, decisione del progettista, skip onesto. |

LLM `source=review` / `pcb_review` → sempre **REVIEW**, mai RULE.

---

## 4. Intent + memoria DECISION

Il progettista può dichiarare un intent (es. **PSEL tied low on purpose**). Persistenza: `decisions.json` nel progetto, fingerprint:

`{rule_id\|source}|{designator}|{net}|{aspect}`

`wontfix` / `false_positive` sul report **scrive** una DECISION. Al rescan il motore **non ri-naga** come ERROR: finding `suppressed=true`, `finding_class=INFO`, `decision_id` valorizzato.

---

## 5. Severity, confidence, evidence — indipendenti

- `status` (severity): ERROR | WARNING | INFO
- `confidence`: 0–1 (quanto è solido il FACT+REQUIREMENT)
- `evidence_status`: SUFFICIENT | INSUFFICIENT

Alto confidence + INFO è legale (misura chiara, non è un fault). Bassa confidence + ERROR **non** è legale se evidence è INSUFFICIENT: si declassa.

---

## 6. Oggetto finding (riproducibile)

Campi obbligatori del motore (oltre a designator / MPN / ids esistenti):

```
facts, requirement, inference
source (pagina/MPN/rule_id)
calculation
assumptions[]
confidence
status (severity)
action          # cosa fare; UI usa anche recommendation
provenance
finding_class
evidence_status
decision_id? suppressed?
```

---

## 7. Libreria unica / esame unico

| Store | Path |
| --- | --- |
| Estrazioni IC | `library/extracted/{safe_mpn}.json` (shared) ∪ `extracted/` progetto |
| PDF blob | `library/datasheets/blobs/{md5}.pdf` |

PCB: `review_ic_async(..., pdf_path=None)` se c’è pintable. Skip: `no library extraction — run schematic review first`.

---

## 8. Cosa è solo PCB

Geometria board: width/thickness, via, pour courtyard, placement mm, return/stitch, pad-net vs schema (`PE-LAY-*` gerarchia `/net`). **Non** duplicare check schema (mux, LED, filtri netlist).

---

## 9. Fasi (non fingere completezza)

**Fase A:** oggetto finding + clamp provenance/class (**ERROR solo se RULE e MANDATORY**) + decisions + UI schema/PCB + libreria condivisa + check geometria già gated.

**Fase B (questa slice):** gerarchia component→pin→net→block; derating PASS/MARGIN/RISK da Vop/Vrated; timing RC/strap solo con numeri; PI local vs bulk; ESD e return path come REVIEW.

**Fase B close-out:** BOM↔PCB↔datasheet (package/pinout/V/T/I); SPOF REVIEW; EMI solo con FACT in `layout_rules`; Tj da θJA+rame+via quando tutti i parametri ci sono.

**Fase B leftovers:** thermal FEM / OpenEMS; ImpedenceFinder LICENSE UNKNOWN; auto-place pcbnew; PinScope identity.