periscope/.cursor/rules/10-architecture.mdc

---
alwaysApply: true
---

# 7. DETERMINISTIC CORE

The verification core must be deterministic.

For the same:

```text
input
+
configuration
+
source data
```

Periscope must produce the same:

```text
model
calculations
findings
```

Do not make deterministic verification dependent on:

* LLM output;
* prompts;
* randomness;
* execution order;
* hidden state;
* uncontrolled external state.

---

# 8. LLM ROLE

LLMs may be used for:

* extraction;
* classification;
* datasheet interpretation;
* explanation;
* hypothesis generation;
* assistance.

LLMs must not be the authoritative deterministic verification engine.

The intended architecture is:

```text
SOURCE
  ↓
STRUCTURED REQUIREMENT
  ↓
DETERMINISTIC ANALYZER
  ↓
FINDING
  ↓
OPTIONAL LLM EXPLANATION
```

Not:

```text
SOURCE
  ↓
LLM
  ↓
probably wrong
```

---

# 9. EVIDENCE BEFORE CONCLUSION

Every engineering conclusion must be traceable to evidence.

Where applicable, preserve:

```text
observed fact
requirement
source
calculation
assumption
conclusion
confidence
severity
```

Do not silently transform assumptions into facts.

---

# 10. REQUIREMENT STRENGTH

Requirements must preserve their strength.

Use:

```text
MANDATORY
RECOMMENDED
TYPICAL
EXAMPLE
ENGINEERING_INFERENCE
```

Do not convert:

```text
RECOMMENDED
```

into:

```text
MANDATORY
```

Do not convert an example into an absolute rule.

Do not convert an engineering inference into documented manufacturer information.

---

# 11. SEVERITY AND CONFIDENCE ARE INDEPENDENT

A finding must be able to represent independent:

```text
severity
confidence
```

Examples that are valid:

```text
ERROR + LOW confidence
RISK + HIGH confidence
```

Do not use confidence as a substitute for severity.

---

# 12. INSUFFICIENT EVIDENCE

If the available information is insufficient to establish a conclusion:

```text
INSUFFICIENT_EVIDENCE
```

must be used.

Never invent missing engineering information.

Never invent:

* electrical limits;
* timing values;
* pin functions;
* voltages;
* currents;
* tolerances;
* PCB rules;
* thermal limits;
* datasheet requirements.

Missing evidence is not permission to guess.

---

# 13. SEMANTIC MODEL FIRST

Periscope must preserve domain semantics.

At minimum, distinguish concepts such as:

```text
Project
Component
Pin
Footprint
Pad
Net
Via
Track
Zone
PowerRail
SignalGroup
TimingEvent
Requirement
Constraint
DesignIntent
Evidence
Finding
```

Do not collapse semantically different physical objects into one generic object merely because they share coordinates, nets, or attributes.

---

# 14. SEMANTIC IDENTITY MUST SURVIVE TRANSFORMATIONS

A transformation must preserve the semantic identity of objects.

For example:

```text
PCB Via
```

must never become:

```text
Component Pad
```

merely because:

* it is close to a footprint;
* it is inside a footprint area;
* it is connected to GND;
* it shares a net;
* it has coordinates similar to a pad.

Similarly:

```text
Pad ≠ Via
Track ≠ Via
Zone ≠ Pad
Component Pin ≠ PCB Via
```

This is a fundamental Periscope rule.

---

# 15. ROOT CAUSE OVER SYMPTOM

When a false positive or incorrect result is discovered:

Do not simply suppress the finding.

Determine where the representation first becomes incorrect.

Example:

```text
PCB
 ↓
parser
 ↓
incorrect model
 ↓
correct analyzer operating on incorrect model
 ↓
incorrect finding
```

The fix belongs in the model/parser boundary, not necessarily in the analyzer.

Always investigate the complete chain:

```text
source
→ parser
→ normalized representation
→ semantic model
→ analyzer
→ finding
→ report
```

---

# 16. NO COMPONENT-SPECIFIC HACKS

Do not fix architecture problems with:

```text
if component == U1
```

or:

```text
if footprint == X
```

or:

```text
if net == GND
```

or hard-coded corrections such as:

```text
subtract N
ignore N
force expected count
```

unless the condition represents a genuine documented engineering rule.

A bug in generic PCB semantics must receive a generic semantic fix.

---

# 17. PHYSICAL SEMANTICS

Periscope is an electronic design verification system.

Its internal model must reflect physical reality.

Geometric proximity does not establish semantic identity.

For example:

```text
Via located inside footprint
```

does not imply:

```text
Via belongs to component as a pad
```

unless the PCB data model explicitly establishes that relationship.

Do not infer component relationships solely from proximity when stronger source information exists.

---

# 18. UNITS MUST BE EXPLICIT

Use explicit units.

Prefer:

```text
width_mm
delay_ns
frequency_hz
voltage_v
current_a
temperature_c
```

over ambiguous variables such as:

```text
width
delay
value
limit
```

when unit ambiguity is possible.

Never rely on undocumented implicit units.

---

# 19. NAMED CONSTANTS

Avoid magic numbers.

Prefer:

```text
MIN_SUPPLY_V
MAX_TRACE_LENGTH_MM
DEFAULT_SPI_CLOCK_HZ
```

over unexplained numeric literals.

Engineering constants must have traceable sources where appropriate.

---

# 20. ERROR CATEGORIES

Distinguish:

```text
tool failure
data failure
analysis result
insufficient evidence
engineering violation
```

Do not collapse fundamentally different failure modes into one generic error.

---