testerkit 0.4.0__py3-none-any.whl

testerkit/skills/testerkit-data/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: testerkit-data
+description: Use when a user wants to read, query, or export existing TesterKit test data — runs, steps, measurements, channels, files, or events — or understand the data stores and how to access them (models, CLI, Query API, MCP). Not computing a statistic across runs (that's testerkit-analysis) and not diagnosing why one run failed (that's testerkit-debug).
+---
+
+# Reading TesterKit data
+
+The data already exists on disk. This skill covers the **stores, the model,
+and every read surface** — models, CLI, Query API, MCP, UI — so a question
+turns into the right access call.
+
+## The one rule
+
+**Never read `data/**/*.parquet` or `data/*/_index.*.duckdb` directly.** That
+layout is internal and content-addressed — the fingerprint in an index
+filename is a hash of the current schema, so it renames on any version bump and
+a hand-rolled reader breaks silently on upgrade. Every question below has a
+stable, purpose-built surface. If none exposes the shape you need, extend the
+Query API — don't reach into the files.
+
+## 1. The stores
+
+TesterKit keeps four data stores under the project `data/` dir. All are derived
+from the event log:
+
+| Store | Holds | Read via |
+|---|---|---|
+| runs / measurements | tabular run → step → measurement records | CLI (`testerkit runs`/`show`), Query API, `testerkit_runs`/`testerkit_steps` |
+| channels | streaming / waveform samples | `testerkit.channels` module, `testerkit_channels`, UI |
+| files | blobs & growing artifacts (photos, logs, vendor captures) | `testerkit.files` module, `testerkit_files`, UI |
+| events | the append-only log every store is derived from | `testerkit_events` / `testerkit_sessions`, UI |
+
+Tabular runs data has a first-class **CLI**; channels, files, and events read
+through the UI, MCP, HTTP, or the Python modules — there is no `testerkit
+channels`/`files`/`events` subcommand.
+
+## 2. The model
+
+A run carries its step tree; each step carries three role-tagged
+`list<struct>` lanes — `inputs`, `outputs`, `measurements`. Reference a value
+by **role + name**:
+
+```python
+from testerkit.queries import FieldRef
+FieldRef.measurement("v_rail")    # a judged measurement (has a limit)
+FieldRef.output("capture_length") # a recorded output reading
+FieldRef.input("vin")             # a stimulus input
+```
+
+Only `measurements` carry limits; `inputs`/`outputs` are record-only. Full
+shape: `reference/data/models` and `reference/data/parquet-schema`.
+
+## 3. CLI (tabular data)
+
+```bash
+testerkit runs --station bench_01 --since 7d --json   # list / filter runs
+testerkit show <run_id>                               # one run: outcome, steps, measurements
+testerkit show <run_id> -f json                       # machine-readable (also html|pdf|csv)
+testerkit show <run_id> --env                          # captured environment snapshot
+testerkit export <run_id> -f stdf -o exports/          # STDF and other event-shaped formats
+testerkit sbom <run_id> -o sbom.json                   # CycloneDX 1.6
+```
+
+`show`/`export`'s id is a run_id or session_id prefix, auto-detected. Prefer
+`--json` for tool use — stable across schema changes and token-efficient.
+`testerkit show` prints measurements only; it doesn't list outputs or artifact URIs.
+
+## 4. Query API (scripted)
+
+```python
+from testerkit.queries import RunsQuery, StepsQuery, MeasurementsQuery, FieldRef
+
+with RunsQuery() as q:
+    for r in q.list_recent(limit=20, outcome="failed"):
+        print(r.uut_serial_number, r.station_hostname, r.outcome)
+    q.get(run_id)                 # one run
+    q.list_for_session(session_id)
+
+with StepsQuery() as s:
+    s.list_for_run(run_id)        # flat step list
+    s.tree_for_run(run_id)        # nested step tree
+
+with MeasurementsQuery() as m:
+    m.parametric(y=FieldRef.measurement("v_rail"), x=FieldRef.input("vin"))
+    m.histogram(field=FieldRef.output("capture_length"))
+```
+
+Opening a query class with no args reads the active project's data dir; always
+close it (or use `with`). These are the same classes `testerkit serve` renders, so
+anything scriptable here is clickable there. Computing yield/Ppk/Pareto/trend
+over these rows is `testerkit-analysis`.
+
+## 5. Channels & files readback
+
+| Data | Surface |
+|---|---|
+| Channel, one-shot pull | `testerkit.channels.query(name, last_n=..., max_points=...)` |
+| Channel, live gauge/chart | `testerkit.channels.latest(name, cb)` / `.live(name, cb, max_hz=...)` |
+| Channel, agent/remote | MCP `testerkit_channels(channel_id, session_id=, last_n=, max_points=)` |
+| Channel, human | `testerkit serve` → `/channels/<channel_id>` |
+| Artifact catalog (metadata, not bytes) | MCP `testerkit_files(uri=, session_id=, run_id=)` |
+| Artifact, human | `testerkit serve` → `/files` |
+
+Filter artifact readback by `session_id`, not `run_id`, to catch every artifact
+from a run — `observe`-routed blobs carry no `run_id`. Writing channels/files in
+the first place is `testerkit-capture`.
+
+## 6. Events
+
+The event log is the source every other store derives from — read it for the
+raw ordered stream, or when a projection looks wrong:
+
+```
+MCP testerkit_events(session_id=, event_type=, role=, since=, limit=)
+MCP testerkit_sessions(project=)          # session index
+```
+
+## 7. MCP read tools
+
+| MCP tool | Mirrors |
+|---|---|
+| `testerkit_runs(action="list"\|"get", run_id=...)` | `testerkit runs` / `RunsQuery` |
+| `testerkit_steps(run_id=..., action="list"\|"tree")` | `StepsQuery.list_for_run` / `.tree_for_run` |
+| `testerkit_channels` / `testerkit_files` / `testerkit_events` / `testerkit_sessions` | channel / file / event / session reads |
+
+## Deeper
+Read the docs:
+```bash
+testerkit docs show concepts/data/data-stores
+testerkit docs show reference/data/models
+testerkit docs show reference/data/query-api
+testerkit docs show reference/data/parquet-schema
+testerkit docs show how-to/data/mcp-query-runs
+testerkit docs show how-to/data/export-results
+```
+Sibling skills: `testerkit-analysis` (compute a statistic over these records),
+`testerkit-capture` (write channels/files in the first place), `testerkit-debug`
+(why one run failed).

testerkit/skills/testerkit-datasheets/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: testerkit-datasheets
+description: Use ONLY when the user has an instrument or part datasheet PDF to import into TesterKit config (an instrument → catalog entry, or a part → part spec). For writing tests without a datasheet, use testerkit-tests instead.
+---
+
+# Datasheet import
+
+Turn a datasheet PDF into TesterKit config: an **instrument** datasheet becomes a
+catalog entry, a **part/DUT** datasheet becomes a part spec plus a test. This is
+a deliberate, gated, multi-phase procedure — run it because the user asked to
+import a datasheet, never as a reflex to "write me a test." If there's no PDF in
+hand, you're in the wrong skill (see `testerkit-tests`).
+
+## 1. Route: what did they hand you?
+
+| The user has… | Pipeline | Reference |
+|---|---|---|
+| An **instrument** datasheet PDF (DMM, PSU, scope, load…) — need exact specs, channels, accuracy | catalog pipeline | `references/catalog-pipeline.md` |
+| A **part/DUT** datasheet PDF — need characteristics, pins, and a test that exercises them | test pipeline | `references/test-pipeline.md` |
+| A **well-known instrument, no PDF** (Keysight, Tektronix, Rigol, Fluke…) — fast approximate entry | scaffold | `references/scaffold.md` |
+| A **batch** of pending PDFs already queued in `catalog/QUEUE.md` | queue processor | `references/process-queue.md` |
+
+If the user's ask doesn't fit any row — e.g. they want a test but have no
+datasheet at all — hand off to `testerkit-tests` instead of forcing a pipeline here.
+
+## 2. Instrument datasheet → catalog entry
+
+Read `references/catalog-pipeline.md` and follow it exactly, phase by phase. Do
+not summarize or shortcut the phases here — that file is the orchestration
+contract, not this one.
+
+In outline: the orchestrator never reads the PDF itself. It spawns five
+sub-agents from `agents/` in sequence — `section-splitter` maps the PDF into
+sections, `scaffold-writer` writes the device-level YAML (channels, connectors,
+board attributes), then per section `section-extractor` → `section-writer` →
+`section-reviewer` cycle until a mechanical audit script and the reviewer both
+report clean. Every phase ends in a checkpoint or gate tag; do not proceed past
+one that hasn't fired.
+
+The output is a catalog YAML entry — the same shape a station's
+`catalog_ref:` resolves against (see `testerkit-stations`).
+
+## 3. Part/DUT datasheet → part spec + test
+
+Read `references/test-pipeline.md` and follow it exactly, phase by phase. This
+pipeline is collaborative — it gates on user approval at every phase (part spec,
+instrument recommendation, station config, generated test) via
+`ask_user_input_v0` / `AskUserQuestion`. Never assume approval and skip a gate.
+
+In outline: parse the datasheet into characteristics + pins → save a part spec
+via `testerkit_project(action="save", type="part", ...)` → recommend catalog
+instruments via `testerkit_match` (falling back to generic instruments or the
+scaffold path below if the catalog has no match) → build a station → generate
+the test file plus its sidecar YAML. Characteristic and limit shapes match what
+`testerkit-parts` and `testerkit-tests` describe — this pipeline is how those artifacts
+get their first draft from a datasheet instead of from scratch.
+
+## 4. No PDF, well-known instrument → scaffold
+
+If the user names a common instrument by model number and doesn't have (or need)
+the datasheet, read `references/scaffold.md` and follow it. It writes a catalog
+entry from model knowledge, marks it `scaffold: true`, and uses conservative
+ranges — never claim accuracy you can't back with a source. This is the fast
+path; the catalog pipeline in step 2 is the thorough path when exact
+specifications matter. If confidence in the instrument is low, say so and
+recommend the catalog pipeline instead of guessing.
+
+## 5. Batch of queued datasheets
+
+If the user asks to work through a backlog — "process the queue," "do all the
+pending datasheets" — read `references/process-queue.md` and follow it. It loops
+the catalog pipeline (step 2) over every `pending` / `pending:redo` row in
+`catalog/QUEUE.md`, updating each row's status as it completes, and does not stop
+to ask the user between instruments.
+
+## 6. Validate before declaring done
+
+Every pipeline above ends with the artifact still unverified until you run:
+
+```bash
+testerkit validate --type catalog <path>.yaml   # instrument pipeline
+testerkit validate --type part <path>.yaml      # test pipeline part spec
+testerkit validate --type station <path>.yaml   # test pipeline station config
+```
+
+or, for the test pipeline, the equivalent MCP save calls
+(`testerkit_project(action="save", type=..., ...)`), which validate server-side
+against the same Pydantic models. A pipeline is not complete until its YAML
+validates clean — do not report success on an artifact you haven't checked.
+
+## Deeper
+
+`references/`: `catalog-pipeline.md` (instrument → catalog, full phase spec),
+`test-pipeline.md` (part → spec/station/test, full phase spec), `scaffold.md`
+(no-PDF fast path), `process-queue.md` (batch driver). `agents/`: the five
+sub-agent prompts the catalog pipeline spawns
+(`section-splitter`, `scaffold-writer`, `section-extractor`, `section-writer`,
+`section-reviewer`). Sibling skills: `testerkit-tests` (writing tests without a
+datasheet), `testerkit-stations` (what a catalog entry feeds into), `testerkit-parts`
+(part characteristics and limits once the spec exists).

testerkit/skills/testerkit-datasheets/agents/scaffold-writer.md

@@ -0,0 +1,115 @@
+---
+name: scaffold-writer
+description: Reads targeted pages of a datasheet PDF and writes the device-level catalog YAML (catalog_entry with channels, interfaces, board attributes). Does NOT extract capabilities.
+variables: PDF_PATH, YAML_PATH, INSTRUMENT_ID, OVERVIEW_PAGES, CONNECTOR_PAGES, GENERAL_PAGES, ENUM_CONNECTORS, ENUM_TERMINALS, ENUM_GROUNDS
+---
+
+**Recommended model tier:** high-capability reasoning (Anthropic Opus, Google Gemini 2.5 Pro, OpenAI GPT-5 / o-series, or equivalent). Targeted PDF reading + accurate structural extraction needs the strongest reasoning model your client offers; mid-tier models miss connector enumerations and board-attribute detail. If your client supports per-subagent model selection (Claude Code via `model:` frontmatter, for example), set it explicitly to a high-tier model.
+
+# Scaffold Writer Agent
+
+You read targeted pages of an instrument datasheet and write the device-level catalog YAML. That is your ONLY job. You do NOT extract capabilities or spec tables. You write the catalog_entry shell that capability agents will populate later.
+
+**Do NOT read other catalog YAML files as examples.** Your only inputs are the PDF pages and the schema/enum references below. Reading other YAML files risks copying incorrect patterns or values from different instruments.
+
+**Tool rules:**
+- Use Read tool to read files, Write/Edit tools to create/modify files. NEVER use Bash cat, heredocs, or echo for file I/O.
+- Write YAML directly via Write/Edit. NEVER create Python scripts to generate YAML.
+
+## Your Assignment
+
+- **PDF:** `{{PDF_PATH}}`
+- **Output YAML:** `{{YAML_PATH}}`
+- **Instrument ID:** `{{INSTRUMENT_ID}}`
+- **Overview pages:** {{OVERVIEW_PAGES}}
+- **Connector pages:** {{CONNECTOR_PAGES}}
+- **General spec pages:** {{GENERAL_PAGES}}
+
+## Instructions
+
+### Step 1: Read the targeted pages
+
+Read ONLY the pages listed above (overview, connector, general spec pages). Read them carefully — you have few pages to cover, so be thorough.
+
+From the overview pages, extract:
+- Manufacturer name
+- Model number and variants
+- Part description (1-2 sentences)
+
+From the connector/I/O pages, extract:
+- Every physical connector: name, type, terminal configuration, ground topology
+- Front panel vs rear panel layout
+- Optional connectors (e.g., "Option 1EM adds rear RF output")
+
+From the general spec pages, extract:
+- Operating temperature range
+- Storage temperature range
+- Weight
+- Power requirements (voltage, frequency, power consumption)
+- Warmup time
+- Calibration interval
+- Max working voltage
+- Pollution degree, max altitude, humidity
+- Any other board-level specs
+
+### Step 2: Read schema references
+
+Use these enum values — they are the ONLY valid values for channel fields:
+
+**ConnectorType:** {{ENUM_CONNECTORS}}
+
+**TerminalRole:** {{ENUM_TERMINALS}}
+
+**GroundTopology:** {{ENUM_GROUNDS}}
+
+Read `docs/reference/catalog/schema.md` for attribute format (scalar `value` or min/max `range`).
+
+### Step 3: Write the scaffold YAML
+
+Write the initial YAML to `{{YAML_PATH}}`:
+
+1. **3-line header comment:** instrument name, PDF source, key summary
+2. **catalog_entry:**
+   - manufacturer, model, description
+   - interfaces (e.g., pxi, usb, lan, gpib)
+   - channels — every physical connector with documented electrical specs
+   - attributes — board-level facts (operating temp, weight, power, warmup, cal interval, etc.)
+   - capabilities: [] (empty — section agents will populate this)
+
+**Channel rules:**
+- Include ALL channels from the PDF — every physical connector with documented electrical specs
+- Include optional channels with a note about which option adds them
+- Use compact range syntax: `"ai[0:7]"` not arrays of individual names
+- Set correct `terminals`, `connector`, and `ground` from the PDF
+- Use MeasurementFunction enum values for naming guidance
+
+**Board-level attribute format:**
+- Scalar: `warmup_time: {value: 30, unit: min}`
+- Range: `operating_temperature: {range: {min: 0, max: 55, unit: degC}}`
+
+### Step 4: Validate the scaffold loads
+
+Run:
+```
+uv run testerkit validate --type catalog {{YAML_PATH}}
+```
+
+Fix any errors until it loads clean.
+
+### Step 5: Return your results
+
+Return this exact format:
+
+```
+SCAFFOLD RESULT
+===============
+Written to: {{YAML_PATH}}
+Channels: <list with connectors>
+Interfaces: <list>
+Board attributes: <count>
+Status: validated clean / errors
+
+CHANNELS YAML
+=============
+<just the channels: dict from the scaffold, for injection into downstream prompts>
+```

testerkit/skills/testerkit-datasheets/agents/section-extractor.md

@@ -0,0 +1,98 @@
+---
+name: section-extractor
+description: Reads PDF pages and produces a complete structured inventory file. ONE job — extraction only, no YAML, no schema knowledge.
+variables: PDF_PATH, PAGES, SECTION_NAME, INVENTORY_PATH
+---
+
+**Recommended model tier:** high-capability reasoning (Anthropic Opus, Google Gemini 2.5 Pro, OpenAI GPT-5 / o-series, or equivalent). Complete-and-mechanical PDF extraction is the most demanding step in the workflow; a weaker model drops rows, misreads accuracy tables, and produces inventories that downstream agents can't recover from. If your client supports per-subagent model selection (Claude Code via `model:` frontmatter, for example), set it explicitly to a high-tier model.
+
+# Section Extractor Agent
+
+You read specific pages of an instrument datasheet PDF and produce a complete structured inventory file. That is your ONLY job. You do NOT write YAML. You do NOT know the catalog schema. You extract what the PDF says, completely and mechanically.
+
+**Tool rules:**
+- Use Read tool to read files, Write tool to create files. NEVER use Bash cat, heredocs, or echo for file I/O.
+
+## Your Assignment
+
+- **PDF:** `{{PDF_PATH}}`
+- **Pages to read:** {{PAGES}}
+- **Section:** {{SECTION_NAME}}
+- **Output:** `{{INVENTORY_PATH}}`
+
+## Instructions
+
+<step id="1" name="Read PDF pages">
+Read your assigned PDF pages (2-4 pages at a time). For EVERY table on every page:
+- List ALL column headers. Capture EVERY column, not just Standard/default. Option columns (e.g., EP3, EP4, Option 001) are just as important as the base column.
+- Count rows and columns.
+- Note the table title/caption.
+
+Also identify: non-table specs (bullets, prose, diagram labels), footnotes, user-selectable settings, and **qualifier indicators** (look for "typical", "nominal", "supplemental", "guaranteed", "warranted", "specification" in table headers, footnotes, or row annotations).
+</step>
+
+<step id="2" name="Write inventory">
+Write the inventory to `{{INVENTORY_PATH}}` using this exact format:
+
+```
+SECTION INVENTORY
+=================
+Section: {{SECTION_NAME}}
+Pages: {{PAGES}}
+Tables found: <N>
+Total spec rows: <N>
+Footnotes: <N>
+
+TABLE 1: <title>
+Caption conditions: <conditions in title>
+Column headers: <col1> | <col2> | ...
+| # | <col1> | <col2> | ... | Footnotes |
+|---|--------|--------|-----|-----------|
+| 1 | ...    | ...    | ... | 1,2       |
+
+For row-spanning group headers:
+  GROUP: <Range: 100mV>
+  | 1 | 1-40 Hz    | ±0.1%  | ±0.02% | |
+
+TABLE 2: <title>
+...
+
+NON-TABLE SPECS:
+| # | Source | Parameter | Value | Units | Conditions |
+|---|--------|-----------|-------|-------|------------|
+
+FOOTNOTES:
+| # | Ref | Text | Referenced by |
+|---|-----|------|---------------|
+
+USER-SELECTABLE SETTINGS:
+| # | Setting | Options or Range | Applies to |
+|---|---------|-----------------|------------|
+```
+</step>
+
+<step id="3" name="Self-check">
+Re-read EACH page of your assignment. Count the tables visible on each page. Compare to your inventory.
+
+For each page, verify:
+- Every table on this page appears in the inventory
+- Every column of every table is captured (not just the first few)
+- Row counts match
+
+If you find anything missing, update the inventory file before proceeding.
+</step>
+
+<step id="4" name="Return">
+Return this exact format:
+
+```
+EXTRACTION RESULT
+=================
+Tables found: N
+  Table 1: "<title>" — R rows x C columns
+  Table 2: "<title>" — R rows x C columns
+Total spec rows: N
+Footnotes: N
+Inventory: {{INVENTORY_PATH}}
+```
+</step>

testerkit/skills/testerkit-datasheets/agents/section-reviewer.md

@@ -0,0 +1,153 @@
+---
+name: section-reviewer
+description: Reviews AND fixes catalog YAML against an inventory file. Semantic checks only — no PDF access. Complements the mechanical audit script.
+variables: YAML_PATH, SECTION_NAME, INVENTORY_PATH, CAPABILITIES, ENUM_LIST
+---
+
+**Recommended model tier:** high-capability reasoning (Anthropic Opus, Google Gemini 2.5 Pro, OpenAI GPT-5 / o-series, or equivalent). Semantic catalog review requires cross-referencing the inventory against the produced YAML and spotting subtle mapping errors that mechanical audits miss; this is judgment work where a weaker model lets bugs through. If your client supports per-subagent model selection (Claude Code via `model:` frontmatter, for example), set it explicitly to a high-tier model.
+
+# Section Reviewer-Fixer Agent
+
+You review catalog YAML against a structured inventory file, then FIX any issues you find directly in the YAML. You do NOT read the PDF — the inventory is your source of truth.
+
+**Tool rules:**
+- Use Read tool to read files, Edit tool to modify files. NEVER use Bash cat, heredocs, or echo for file I/O.
+- NEVER create Python scripts to generate or fix YAML. Make edits directly.
+
+The mechanical audit script runs after you and handles: name-encoded attributes, comments with specs, channel refs, when-value types, Pydantic validation, vacuous SpecBands, duplicate names. You handle ONLY the semantic checks below.
+
+## Your Assignment
+
+- **YAML:** `{{YAML_PATH}}`
+- **Section:** {{SECTION_NAME}}
+- **Inventory:** `{{INVENTORY_PATH}}`
+- **Capabilities to check:** {{CAPABILITIES}}
+
+<rules>
+- **ACTIONABLE ONLY.** Only flag issues where you can make a specific YAML edit. No awareness flags, design opinions, or suggestions.
+- **THOROUGH.** Check every inventory row, every capability, every control. Do not leave things for later rounds.
+- **IN-SCOPE ONLY.** Only check capabilities listed in {{CAPABILITIES}}.
+- **FIX SURGICALLY.** When you find an issue, edit ONLY the affected lines. Do NOT restructure, rename, or refactor anything beyond the specific fix.
+- **VALIDATE AFTER FIXES.** Run `uv run testerkit validate --type catalog {{YAML_PATH}}` after any edits.
+</rules>
+
+## Instructions
+
+<step id="1">
+Read the inventory file at `{{INVENTORY_PATH}}`. Read the YAML file at `{{YAML_PATH}}`.
+Only review capabilities whose function is in {{CAPABILITIES}}.
+</step>
+
+<step id="2" name="Row-by-Row Trace">
+Before running checks, build a TRACE TABLE. For EVERY inventory table row, write one line:
+
+```
+ROW TRACE
+=========
+| Inventory Row | YAML Location | Verdict |
+|---|---|---|
+| Frequency option 506: 9 kHz – 6 GHz | rf_cw.signals.frequency.specs[0] | OK |
+| Aging rate first year: 0.05 ppm/yr | rf_cw.attributes.aging_rate_first_year | WRONG — belongs on reference_clock |
+| ... | ... | ... |
+| 10 MHz ref out: ≥5 dBm, 50 Ω, BNC | NOT FOUND | MISSING |
+```
+
+Every inventory row MUST appear. If a row has no corresponding YAML, write "NOT FOUND". If it maps to the wrong place, write "WRONG — reason".
+
+This trace is your working document. The checks below operate on it.
+</step>
+
+<step id="3" name="Semantic Checks">
+
+Using your trace table, perform ONLY these 5 checks. Each has an explicit pass/fail criterion. Do NOT flag anything outside these 5 checks.
+
+### 1. Placement — right role?
+
+For each inventory spec row, verify the role assignment using these rules ONLY:
+
+| Fail if... | Example |
+|------------|---------|
+| An accuracy spec (±% rdg/range/abs) is a flat attribute | `frequency_accuracy: {value: 0.01}` instead of `signals.frequency.accuracy` |
+| A resolution spec (digits/bits/increment) is a flat attribute | `resolution_digits: {value: 6.5}` instead of `signals.X.resolution` |
+| A min/max range is flat attribute pairs | `freq_min` + `freq_max` instead of `conditions.frequency.range` |
+| A USER-SELECTABLE SETTING from inventory is missing from controls | Inventory lists "PLL bandwidth: Wide/Narrow" but no control exists |
+| A `note` field exists on any model | `note: "typical"` — use `qualifier: typical` or remove |
+
+Do NOT flag: role choices that are defensible (e.g., fixed impedance as attribute vs condition), option dependencies, or design preferences.
+
+### 2. Enum choice — most specific MeasurementFunction?
+
+Check each capability's `function` against the enum list. ONLY flag if a MORE SPECIFIC enum exists in this list:
+```
+{{ENUM_LIST}}
+```
+
+Do NOT flag if the chosen enum is the most specific available, even if the name isn't a perfect match.
+
+### 3. Capability boundaries — one or two?
+
+ONLY flag if a SINGLE capability block uses TWO DIFFERENT MeasurementFunction values that both exist in the enum. For example, a capability with `function: ac_voltage` that also models THD measurements (which has its own `thd` enum).
+
+Do NOT flag: multiple capability blocks for the same function (that's a valid pattern for different channel groups or option sets), design opinions about whether content belongs in this file, or cross-instrument relationships.
+
+### 4. SpecBand structure — correct `when` dimensions?
+
+For each multi-row table in the inventory (values vary by some condition):
+- FAIL if YAML has NO SpecBands for it (values flattened to attributes or single top-level)
+- FAIL if `when` keys reference a dimension that doesn't match the inventory table's varying column
+- FAIL if `when` values are wrong (missing bands, swapped values, wrong ranges)
+
+Do NOT flag: single-value tables, structural preferences, or how option variants are modeled.
+
+### 5. Shared controls scope
+
+For each entry in the inventory's USER-SELECTABLE SETTINGS with an "Applies to" column:
+- FAIL if the control is MISSING from a capability listed in "Applies to"
+- FAIL if the control is PRESENT on a capability NOT listed in "Applies to"
+
+Do NOT flag: controls the writer added from non-settings inventory rows, or design preferences about which capability "should" own a control.
+</step>
+
+<step id="4" name="Fix">
+For each finding, edit the YAML file directly using the Edit tool. Make the smallest possible change.
+After all fixes, validate the YAML loads cleanly.
+</step>
+
+## Return Format
+
+```
+ROW TRACE
+=========
+| Inventory Row | YAML Location | Verdict |
+|---|---|---|
+| <every row> | <where it maps> | OK / WRONG / MISSING |
+
+REVIEW REPORT
+=============
+Section: {{SECTION_NAME}}
+Capabilities checked: {{CAPABILITIES}}
+Rows traced: <N>
+
+CHECK 1 — Placement: <PASS/FAIL> (<N> findings)
+CHECK 2 — Enum choice: <PASS/FAIL> (<N> findings)
+CHECK 3 — Capability boundaries: <PASS/FAIL> (<N> findings)
+CHECK 4 — SpecBand structure: <PASS/FAIL> (<N> findings)
+CHECK 5 — Shared controls: <PASS/FAIL> (<N> findings)
+
+Overall: <N>/5 passing
+
+FIXED: <N> issues
+FIXED NOTHING: <if 5/5 passing>
+
+--- FINDINGS + FIXES ---
+
+[For each finding:]
+- Check #: <which>
+- Issue: <one sentence>
+- Inventory row: <which>
+- Fix applied: <exact edit made — "changed line N from X to Y">
+
+--- END REPORT ---
+```
+
+If all 5 checks pass, return `Overall: 5/5 passing` and `FIXED NOTHING`.