Pinscope open-source core

Agentic schematic validation: datasheet extraction via Claude Console
Skills, netlist/BOM design graph, per-IC direct datasheet review with
page citations, capacitor derating, Next.js report UI.

Extracted from the Pinscope cloud codebase. Auth and billing live in the
private gateway repo behind stable seams (billing_hook.py, adapter files
listed in CLAUDE.md).

docs/review-false-positives.md

@@ -0,0 +1,168 @@
+# Review false positives — case log
+
+Real false positives caught in the wild, with the root cause and the
+reviewer-prompt change (or open work) that addresses them. Use this as
+the seed corpus when evaluating future prompt edits — a change is only
+worth landing if it would have prevented or downgraded one of these
+without regressing the true findings.
+
+## U1-002 — "5V DC on RF out via L5 damages internal DC block"
+
+**Project:** `434e247dfa98` (prod, 2026-05-26), version 2.3.1.
+**IC:** U1, CMD263P3 (5–11 GHz LNA).
+**Topology:** L5 (RF choke) connects `+5V` to U1 pin 11 (RF out). C6
+(broadband 0.1 µF) shunts the same node to GND. J2 (RF output coax)
+sits on the same node. Pin 11 is documented as "DC blocked and 50 Ω
+matched" internally.
+
+**What the reviewer flagged (ERROR):** "DC bias being applied to an
+internally DC-blocked RF output … may damage it or degrade RF
+performance."
+
+**Why it's wrong:** this is a textbook **bias-T**. The L+C network
+exists to inject DC onto the coax to power a downstream active device
+(active antenna / external LNA / mixer) through the same cable that
+carries the RF signal back. The chip's *internal* DC block is exactly
+the feature that makes bias-T safe: it isolates the LNA's RF stage
+from the externally applied DC. The internal block cap is rated
+against the chip's package abs-max (≥ Vdd abs max = 5 V here), so 5 V
+across it is a non-event.
+
+**Root cause:** the reviewer correctly identified an unusual topology
+(DC rail on an RF pin) and correctly read the datasheet ("DC blocked
+internally"), but never connected the two. Two reasoning gaps:
+1. **No harm-pathway numbers.** The `why` was pure speculation —
+   "*may* damage", "*may* degrade" — with no abs-max quoted, no
+   voltage stress computed. If the reviewer had been forced to write
+   the inequality (e.g. "internal DC-block cap rated for X V, sees Y V
+   → Y > X"), it would have either produced that proof or dropped the
+   claim.
+2. **No "what is this part for" step.** The reviewer asked "what does
+   L5 do?" and answered "it puts 5 V on the RF pin" — true, but
+   incomplete. The next inference ("the DC doesn't reach the chip
+   because of the internal block, so it must be powering something
+   downstream of J2") never happened.
+
+**Prompt change landed:** new "ERROR requires a concrete harm pathway"
+section in `backend/pinscopex/validate.py:SYSTEM_PROMPT`. Forces every
+ERROR that alleges damage / abs-max violation / stress to name the
+stressed component, the actual voltage/current on it, the datasheet
+limit, and the inequality between the two. Hedged language without
+numbers is no longer enough for ERROR — it must demote to WARNING.
+Also adds an explicit note that *internal* components share the chip's
+package abs-max, so external stress within the pin abs-max cannot
+damage them by definition.
+
+**Expected effect on U1-002:** demotes to WARNING at worst (the
+reviewer can no longer write "may damage" without quantifying the
+stress on the internal cap), or drops entirely once the reviewer
+recognizes the 5 V is below pin abs-max.
+
+## U1-001 — same bias-T, same IC, new project (landed: role-of-part step)
+
+**Project:** `13730c6991e3` (staging, 2026-05-26), version 2.3.1.
+**IC/topology:** identical to U1-002 above — CMD263P3, L5 bias-T on
+pin 11 (RF out), C6 shunt, J2 coax. Different project, same false
+positive class.
+
+**Why harm-pathway alone wasn't enough:** the reviewer now cites
+numbers (the gate's letter is satisfied), but the inequality is
+bogus on two counts:
+1. Wrong pin's abs-max — "places the RF output node at 5.0V — equal
+   to the absolute maximum **Vdd** rating (5.0V)" cites Vdd's limit
+   (pin 14) against pin 11 (RF out).
+2. `=` is not `>` — abs-max is the don't-exceed line; *at* abs-max is
+   not damage.
+
+**Trace evidence:** the reviewer reached the right premise on its
+own at turn 2 — *"L5 is an RF choke connecting RF_out to +5V. This
+is a DC bias injection topology — but the datasheet says pin 11 is
+'DC blocked and 50 ohm matched' internally"* — then dropped the
+inference. The next step ("if the DC doesn't reach the chip, what
+*is* it powering?") never happened. Both halves of the proof were
+named in the same sentence; only the conclusion was missing.
+
+**Prompt changes landed:**
+1. New "Identify the role of each external part before judging it"
+   section in `SYSTEM_PROMPT`, positioned before the "Net names" /
+   "Cross-IC interface" sections. Forces a four-step derivation
+   (pin behavior → part class → where the other end goes → role)
+   per external component, from first principles. Explicitly: when
+   a documented pin characteristic *prevents* the surface-reading
+   interaction (DC-blocked pin, AC-coupled pin, …), the part is
+   serving the rest of the circuit, not the chip.
+2. New "Budget per concern: at most two follow-up tool calls"
+   section — caps deep-dive on one concern to two queries, demotes
+   to WARNING with `Unverified:` rather than burning turns. Stops
+   the death-spiral pattern where one suspect finding starves the
+   rest of the IC review.
+3. Harm-pathway gate tightened: (a) abs-max number must come from
+   the *same pin's* abs-max row, not a different pin's; (b) strict
+   inequality (`>`, not `≥`) — equal-to-abs-max is at most WARNING.
+4. `_MAX_REVIEW_TURNS` raised from 8 to 10 to absorb the role step
+   without truncating the rest of the review.
+
+**Expected effect on U1-001:** drops entirely once the reviewer
+states "L5 + DC-blocked pin 11 + downstream J2 → bias-T powering a
+downstream load". If the role step is skipped for any reason, the
+tightened gate still demotes to WARNING (Vdd abs-max is no longer
+valid as the limit for pin 11; `=` is no longer enough).
+
+**Open follow-ups:**
+- Re-run this project (`/restart` admin path) to confirm U1-001
+  drops or demotes. Add the resulting trace turn count as a sanity
+  check that 10 turns is enough.
+- Watch the next 2–3 production runs for *regressions* — the role
+  step adds one reasoning pass per external part and could in
+  theory cause the reviewer to over-explain valid concerns as
+  WARNING. If any true ERROR demotes incorrectly, log it here.
+
+## Historical: "what is this part for?" reasoning step (now landed above)
+
+The harm-pathway requirement catches U1-002 by raising the bar on
+ERROR. The deeper fix — and the one that catches the whole *family* of
+unusual-but-correct RF topologies (bias-T, AC coupling, matching
+networks, baluns, π/T attenuators) — is a forced reasoning step:
+**for every external part on a chip pin, state what role it plays in
+the design *before* judging whether it's correct.**
+
+The chain that kills U1-002 directly:
+
+> L5 connects +5 V to pin 11. Pin 11 is internally DC-blocked.
+> Therefore the DC does not reach the chip. Therefore L5 must be
+> powering something downstream of J2. → bias-T topology, expected.
+
+The chain that kills the U3-001/U1-001 contradiction (a separate but
+related issue from the same project):
+
+> Net `$1N2250` is labeled 1.48 V but the ADJ divider math says 3.70 V.
+> Which is the cause and which is the consequence? The divider is
+> physical (resistor values), the label is an annotation. Trust the
+> physics. → U1-001 ("Vdd below 2 V min") is the false consequence of
+> trusting the label.
+
+**Status: landed** — see U1-001 case above. The role-of-part step
+went in alongside the harm-pathway gate tightenings and a per-concern
+turn budget, after the U1-001 run (same false-positive class, fresh
+project) confirmed the harm-pathway change alone was not enough.
+
+**Original deferral rationale (retained for context):** the
+harm-pathway fix was one prompt section and shipped first. The "what
+is this part for" step is structurally larger — it changes the
+reviewer's loop (one extra reasoning pass per external component)
+and is more likely to regress true findings if done sloppily. Worth
+doing after we've seen the harm-pathway change in production for a
+few runs — which is exactly what U1-001 provided.
+
+**Pointer for whoever maintains this section:**
+- The reasoning step lives *before* the existing "Net names are not
+  voltage labels" / "Cross-IC interface checks" sections in
+  `SYSTEM_PROMPT` — it's a precondition to those.
+- Canonical RF patterns (bias-T, AC coupling, …) are deliberately
+  NOT listed by name. The win of agentic review over a pattern
+  library is that the reviewer figures out the role from first
+  principles. Don't add patterns to the prompt — add reasoning
+  scaffolds instead.
+- Cross-check against this file: any prompt change that no longer
+  prevents U1-002 / U1-001 (and the future cases logged below them)
+  is a regression.