periscope/docs/motore-finding.md

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 (questa slice): oggetto finding + clamp provenance/class + decisions + UI schema/PCB + libreria condivisa + check geometria già gated.

Fase B (pianificata): gerarchia component→system; timing; energy/thermal solo con θJA/P/I_load; ratings; derating PASS/MARGIN/RISK; PI; SI oltre skew mm; return path oltre stitch INFO; ESD/EMI; thermal FEM; BOM↔PCB↔datasheet; SPOF come REVIEW.