CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ThomsonLint is a knowledge and rule framework for AI-assisted hardware design review. It provides structured, machine-readable resources that enable AI models to analyze and identify potential issues in hardware designs (schematics and PCB layouts). The tested driver is Claude Code; a single-file-upload bundle exists for web AIs (e.g., Gemini, Claude.ai, ChatGPT) but that workflow has not been validated.

The framework is named after J.J. Thomson, discoverer of the electron, reflecting its goal of uncovering fundamental issues in hardware designs.

## Core Components

- **`ontology/ontology.json`** - Machine-readable JSON defining rules, domains, severity levels, and failure modes for hardware design review
- **`examples/examples.json`** - Practical examples (good and bad) that map to ontology rules, used for training/testing AI understanding
- **`docs/AI_Hardware_Design_Review_KnowledgeBase.md`** - Human-readable explanations and context for the ontology rules
- **`docs/Multi_Agent_Reasoning_Spec.md`** - Specification for multi-agent architecture (Power/SMPS, High-Speed SI, Analog, EMC/ESD, Thermal/Mechanical agents)

## Commands

### Validate JSON files
```bash
pip install jsonschema  # if not installed
python validate_json.py
```

### Generate review instructions file
```bash
./gen_context.sh > review_instructions.txt
```

### Validate findings coverage (mandatory before report)
```bash
python tools/validate_findings.py exports/<project_name>-findings.json
```
Mechanical coverage gate. Schema-validates the findings file, lists every PDF / schematic / board export in the findings file's directory that is not cited in any `evidence[].source`, and reports issues missing required fields. Exit code is non-zero if uncited inputs or missing fields are present. **Run this before generating the HTML report.** This is the gate that prevents the agent from silently dropping datasheet analysis (every PDF the agent opens must end up in the findings file).

### Generate HTML review report
```bash
python tools/gen_report.py exports/<project_name>-findings.json [--output exports/]
```
Takes a findings JSON file (see `tests/findings_schema.json` for the schema; `tests/sample_findings.json` for a worked example) and generates a self-contained HTML report at `exports/<project_name>-review.html`. The report renders three sections: `issues` (interactive Open/Accept/Ignore triage with localStorage persistence), `verified_checks` (read-only — analyses confirmed OK), and `cross_checks` (read-only — design-wide multi-rule analyses).

## Reviewer Paths

Claude Code is the tested reviewer driver. A second path exists for single-file-upload web AIs but has not been validated. Both paths consume one source of truth: `docs/REVIEWER_INSTRUCTIONS.md`.

- **Claude Code (CLI, in this repo) — tested.** The user prompts the agent to read `docs/REVIEWER_INSTRUCTIONS.md` and follow it. Step 1 of that file then directs the agent to load the framework knowledge base from:
  - `ontology/ontology.json`
  - `examples/examples.json`
  - `docs/AI_Hardware_Design_Review_KnowledgeBase.md`

  The project ships a `/design-review` skill at `.claude/commands/design-review.md` — type `/design-review` at the Claude Code prompt instead of pasting the full prompt manually.

  Do **not** read `review_instructions.txt` from Claude Code. The bundle (~260KB / 5700 lines) is intended for single-file upload to a web AI and exceeds Claude Code's per-file `Read` limit. The source files are the truth; the bundle is a concatenation of them.

- **Web AI with single-file upload (Gemini, Claude.ai, ChatGPT, etc.) — untested.** The `review_instructions.txt` bundle is produced by `gen_context.sh`, which concatenates `docs/REVIEWER_INSTRUCTIONS.md` with the three knowledge base files. The maintainers have not validated this path; treat as experimental.

The reviewer-facing flow (inputs, outputs, prompts) is documented in README.md §5 "Running a Review".

## Live Fusion Capture (`tools/fusion_bridge.py`)

The bridge is the HTTP transport to a running Fusion Electronics session over Autodesk's "Fusion MCP Server" endpoint (`ping` / `eagle` / `read` / `stage-ulps` verbs). Step 0 of `docs/REVIEWER_INSTRUCTIONS.md` now runs on `tools/fusion_export.py` (next section), which imports this bridge; driving the ULPs over the bridge (`stage-ulps` + `RUN` dispatches) remains only as a fallback pattern. The ULP-over-bridge path was verified end-to-end 2026-08-28 against a live 1-sheet design before being superseded.

Non-obvious operational facts (learned the hard way — do not rediscover):

- **Dialog latch (known Fusion issue).** Two triggers are confirmed: any dispatch whose EAGLE command contains `RUN`, and any **no-op `EDIT`** (opening the sheet/editor that is already open — isolated by A/B test 2026-08-28). The add-in then refuses further scripts with "Cannot perform 'script' while a command dialog is open" — **no dialog is actually visible**; only a keypress (Escape) in the Fusion window clears it. Detect the clear by polling a no-op `execute_script`. Real editor switches, `RATSNEST`, `DISPLAY`, `WINDOW FIT`, and `EXPORT IMAGE` do not latch. `run_eagle()` auto-prefixes every command with `SET CONFIRM YES;`, which prevents the same latch after confirmation prompts and auto-answers ULP overwrite prompts — but prevents neither trigger above.
- ULP-fallback only: the schematic and board ULP passes **cannot merge into a single dispatch** — the images ULP terminates via `exit()`, which also ends the rest of the chained command line.
- **Reads follow the active editor** and are never latch-blocked. With the board tab active, `electronics.Schematic`/`Sheet`/`Part` read empty — that means "wrong editor", not "no design open" (`ping` detects and reports this case).
- Fusion's screenshot query returns "No active graphics view" for the 2D electronics editors — you cannot remotely see what is on screen.
- **Export/stackup JSONs are Latin-1, not UTF-8** (e.g. the German layer name "gesam-Maß"). Python's `json.load` raises `UnicodeDecodeError`; decode with `latin-1` first. This is a pre-existing trait of the ULP output (the committed comet stack file has the same byte), not a bridge bug.
- ULP PNG renders are fixed-size per canvas: every board PNG of a design is **byte-identical in size** (checksums differ — they are not duplicate renders), and board PNGs can exceed 150MB.
- `run_eagle()` embeds the command into the generated Python via `repr()` **deliberately** — single quotes and Windows backslash paths (`RUN 'C:\...'`) survive. Do not "simplify" it to an f-string.
- **The dialog latch is not only post-`RUN`: a no-op `EDIT` (opening the sheet/editor that is already open) also arms it** — isolated by A/B test 2026-08-28 (real switch → clean; same `EDIT .S1;` repeated → latched). Real switches, `RATSNEST`, `DISPLAY`, `WINDOW FIT`, and `EXPORT IMAGE` do not latch.

## Direct Capture (`tools/fusion_export.py`) — the Step 0 path

ULP-free capture: emits the same `-thomson-export-{sch,brd,stack}.json` contracts from `electronics_read` queries and renders the review PNGs via dispatched `EXPORT IMAGE` chains (verbs `sch` / `brd` / `images` / `all`). Verified against a same-day ULP capture of `series-shunt`: exact parity except documented deltas (`clearance_mm` null — MCP exposes no NetClass clearance; `layers_used` over-reporting; the stackup is *more* correct — the ULP's "ROUTE" name fallback put layer 19 Unrouted in the copper stack). Zero Escapes for 1-sheet designs; its `wait_channel()` prompts and waits if the latch arms. **The comet (routed + poured, round-outline) parity diff passed 2026-08-28** — every delta accounted for, several in the direct path's favor (the ULP was numerically blind to routing and pours on Fusion inner copper 303, and its edge-distance check measured against the drawing extent instead of the board outline). **Step 0 of `docs/REVIEWER_INSTRUCTIONS.md` now runs on this tool** (`python tools/fusion_export.py all`); the ULPs stay in `tools/` solely for the manual fallback path. Details and the intentional deltas: `docs/Direct_Read_Feasibility.md`.

## Pre-Commit Requirement

**Before every commit**, regenerate the `review_instructions.txt` file:
```bash
./gen_context.sh > review_instructions.txt
```

This ensures `review_instructions.txt` is always up-to-date in the repository, allowing users to immediately use it with their design files without needing to run any scripts.

## File Modification Guidelines (from TODO.md)

When modifying files in this repo:

1. **JSON files must contain pure JSON only** - no Markdown headings, commentary, or code fences
2. **Output full file contents** when updating, not diffs
3. **Preserve valid syntax** - ontology.json and examples.json must remain valid JSON
4. **Be explicit** about which file you are updating
5. **Stay conservative about deleting** - prefer appending/expanding over removing unless explicitly told to refactor

## Extending the Framework

When adding new rules or examples:
1. Add entries to `ontology/ontology.json` or `examples/examples.json` following existing structure
2. Update `docs/AI_Hardware_Design_Review_KnowledgeBase.md` if context is needed for new rules
3. Run `python validate_json.py` to validate changes

### Source Attribution (mandatory)

Content providers supply valuable knowledge to this project, and their efforts must be acknowledged. Every knowledge-base addition derived from external material (a video, article, checklist, book, or a person's contribution) MUST include a `**Source:**` attribution line near the top of the new or updated KB section in `docs/AI_Hardware_Design_Review_KnowledgeBase.md`:

```
**Source:** <author/contributor>, <publication or channel>, <URL> — optionally followed by the specific video/article title and link.
```

Existing examples to follow:
- Appendix J: `**Source:** Hans Rosenberg, hans-rosenberg.com`
- Appendix I.4: `**Source:** John Teel, Predictable Designs, https://www.youtube.com/@PredictableDesigns — video "9 Voltage Regulators You Should NEVER Use in Your Product" (youtu.be/KM8I2idEsF4).`

Prefer the author's main channel/site URL so readers can find their broader body of work; add the specific item for traceability. Content distilled from general engineering practice with no single identifiable source does not need an attribution line.

### Ingesting YouTube Content (transcript + creator attribution)

When asked to pull a transcript from a YouTube video (typically as raw material for a KB addition), use the helper script:

```bash
python tools/yt-transcript.py <youtube-url> [--output <dir>]
```

It downloads the video's English captions via yt-dlp, cleans the rolling-caption duplicates into timestamped paragraphs, and writes `<video-id>-transcript.txt` with a header containing the title, creator name, creator homepage URL, video URL, upload date, and duration. Output goes to `/tmp` by default — transcripts are working material for KB distillation and must not be committed to the repo.

Notes:
- **yt-dlp must be current** — YouTube routinely breaks old versions. If the system `yt-dlp` fails with extraction errors, install the latest into a venv and pass it explicitly:
  ```bash
  python3 -m venv /tmp/ytdlp-venv && /tmp/ytdlp-venv/bin/pip install -U yt-dlp
  python tools/yt-transcript.py <url> --yt-dlp /tmp/ytdlp-venv/bin/yt-dlp
  ```
- **Mandatory follow-up — creator homepage.** After pulling the transcript, go to the creator's YouTube homepage (the "Creator homepage" URL in the transcript header, e.g. `https://www.youtube.com/@PredictableDesigns`) and gather the creator's information: creator/host name, channel name, channel description, and any external website or business links they list. This information is what populates the `**Source:**` attribution line (see "Source Attribution" above) when the transcript becomes a KB addition. Do not write the KB section without it.

### Ontology Rule Structure
Each rule includes: `id`, `name`, `domain`, `description`, `applies_to`, `conditions`, `default_severity`, `failure_modes`, `recommended_actions`, `kb_references`

### Example Structure
Each example includes: `id`, `title`, `description`, `triggered_rules`, `expected_issue`

### Findings File Structure (output of a review)
Top-level fields: `project_name`, `review_date`, `source_documents`, `issues`, `verified_checks`, `cross_checks`. The three findings arrays share one entry shape — see `tests/findings_schema.json` and `tests/sample_findings.json`.

- **`issues[]`** — problems requiring designer triage. Severity, description, recommended_actions all required.
- **`verified_checks[]`** — analyses the agent performed where the result was OK. Read-only in the report. Crucial: do NOT omit a verification because nothing was wrong; the verification itself is a deliverable.
- **`cross_checks[]`** — design-wide analyses spanning multiple ontology rules (e.g., MT3608 layout cross-check covering PWR_BUCK_001/002/003/004 plus thermal). `rule_id` may be an array.
- **Per-entry `evidence[]`** — typed rows. Either parameter comparisons (`label/datasheet/design/margin/verdict/source`) or free-form notes (`note/source`). Every row must cite a `source`. The validator cross-references these against design inputs in the findings directory.

## JSON Schemas

- `tests/ontology_schema.json` - Schema for validating ontology.json
- `tests/examples_schema.json` - Schema for validating examples.json
- `tests/findings_schema.json` - Schema for validating findings JSON files
- `tests/sample_findings.json` - Worked example showing all three sections plus evidence rows

## Hardware Domain Coverage

The ontology covers these domains:
- **Power/SMPS** - Decoupling, buck converter layout, component ratings, compensation networks
- **High-Speed Digital (SI)** - DDR rules, differential pairs, impedance control, clock nets
- **Analog/Mixed-Signal** - Op-amp stability, ADC drivers, sensor front-ends
- **EMC/ESD** - External connector protection, EMI filtering, return paths, ground stitching
- **Thermal/Mechanical** - Power density, thermal vias, connector reinforcement
- **DFT/DFM** - Test points, silkscreen, fiducials