---
name: datasheet-parser-interactive
description: Use this skill — NOT the bare datasheet-parser skill — when a human is present and wants to review a datasheet parse before it's published to the wiki. Wraps the core datasheet-parser workflow with the live visualizer and a mandatory human-approval gate before Step 7 (Publish). Triggers when the user says any of "parse this datasheet for me", "parse the [part] datasheet" (in an interactive session without `--no-visualize`), "I want to review before publishing", "show me in the webview", "interactive parse", "supervised parse", "signoff parse", "let me approve before it goes out". If the user is clearly running an unsupervised batch (e.g. `process-datasheets`), use the bare datasheet-parser instead.
---

# Datasheet Parser — Interactive Mode

Human-supervised variant of `datasheet-parser`. Same output (structured wiki markdown + cropped diagrams + metadata), but the run is visible in the live visualizer panel from start to finish, and publishing is gated on explicit human approval.

## When to use this skill vs. the bare parser

| Situation | Skill |
|---|---|
| User is present, asked you to parse one datasheet | **this skill** |
| User wants to "review / approve / sign off before publish" | **this skill** |
| User references the visualizer / webview panel | **this skill** |
| Called from `process-datasheets` batch (no human at keyboard) | bare `datasheet-parser` |
| User explicitly passed `--no-visualize` | bare `datasheet-parser` |

If in doubt, assume the user wants to see the work before it goes public. This skill is the safe default for interactive sessions.

## Invariants (follow these without exception)

1. **Always `--visualize`.** Run Step 0 of `datasheet-parser` in full — install/start the visualizer at port 8851, create a fresh session, source `bin/emit.sh`, open the viewer in an AV panel with the *new* session ID in the URL. Do not reuse a stale session ID from a prior thread — the browser will silently watch a dead session and the user will see nothing update.
2. **Never skip the visualizer.** If the visualizer server fails to start, STOP and tell the user. Do not fall back to silent processing. The whole point of this skill is that the user can see what's happening.
3. **Emit events at every stage.** `emit_stage download / extract / render / ocr / crop / synthesize / generate / publish / store` around their respective steps, plus `emit_page_rendered`, `emit_page_annotated`, `emit_crop`, `emit_section` inside them. An empty chip sequence in the viewer = the user thinks you're broken.
4. **Pre-resize pages before Read.** The Read tool hard-limits at 2000 px per side in many-image requests. 300-DPI page renders are ~2480×3508 px and will crash the conversation the first time you batch-read them. Produce a `pages-1500/` mirror downscaled to ≤1500 px long edge with `convert … -resize '1500x1500>'` and Read from that mirror. Keep the full-res originals for Step 4c crops.
5. **HARD STOP before Step 7 (Publish).** See [Approval gate](#approval-gate) below. The batch parser publishes unattended; this skill does not.
6. **One session per parse.** Do not merge two datasheets into one visualizer session. If the user asks for a second parse, close the current session with `emit_done ok` and re-run Step 0 for the new one.

## Workflow

Run the full `datasheet-parser` workflow (Steps 0–9) with `--visualize` **set**, with these specific amendments:

- **Step 0** — do not skip. If the install/start block fails (`curl http://127.0.0.1:8851/health` non-OK), surface the error to the user and stop. Do not proceed silently.
- **Step 4a** — after `pdftoppm`, run the mandatory resize to produce `pages-1500/`. Read pages from `pages-1500/` during Step 4b OCR. Use the full-resolution originals for Step 4c crops (PyMuPDF + manual).
- **Steps 4b / 4c / 5** — emit `page_rendered`, `page_annotated`, `crop`, `section` events as specified in the base skill. Do not silently skip any of them — the user's only view into progress is this event stream.
- **Before Step 7** — enter the [Approval gate](#approval-gate). Do **not** run `adom-wiki page publish`, do **not** run `adom-wiki asset upload`, do **not** call the metadata API until the user has explicitly approved.
- **Step 7** — only runs after approval. Then proceed with publish, metadata, and asset uploads as the base skill describes.
- **Step 9** — `emit_done ok` closes the visualizer session cleanly.

## Provenance on every artifact

Every image, table, code block, iframe, or rendered viewer that appears in the wiki page or the visualizer **must** carry a one-line provenance caption directly underneath it. Captions answer the only question a careful reader has: *where did this come from?*

A provenance caption names exactly:
1. **Who/what produced this artifact** — `sym_create`, `generateFootprintViewer()`, `crop_figures.py`, `pdftoppm`, my custom Python script at `<path>`, the KiCad CLI service, `WebFetch` from `<url>`, the original PDF page N figure M, etc.
2. **What it is NOT** — explicitly call out alternative sources the reader might assume. If the image was *not* taken from the datasheet, say so. If the renderer fell back to a local path because a service was down, say so. The "not from X" line prevents false attributions.
3. **Inputs / dependencies** — what the producer consumed (`icebox.py` pin table, JEDEC MS-026 BCD geometry, page-N PNG render, etc.).

Rendering convention in the markdown body: a single Markdown blockquote starting with `> **Provenance — <artifact name>.**` directly below the artifact (image / iframe / table). The leading `>` makes it visually distinct from body prose so a scanning reader spots it instantly.

This applies to:

- Every cropped diagram (page + figure caption, plus the cropper that ran)
- Every generated symbol render (which tool, what input)
- Every generated footprint render (which tool, fallback status)
- Every interactive iframe (what generator, what file path)
- Every pinout table (whose pin database)
- Every spec value the reader might want to double-check (datasheet page + table + row)

If a reader has to ask "did you draw this or did the datasheet?" the caption is missing. The rule from a 2026-04-18 user call-out: *"if you took this image from the datasheet, you need to tell the human. if you drew it custom, tell us. if you asked kicad service to draw it for you, tell us."*

## Approval gate

After Step 6 (metadata JSON written) and before Step 7 (Publish), run this gate:

1. **Pick and emit the hero image FIRST.** Before showing any other artifacts, choose the single best image that represents the whole datasheet (chip photo > block/architecture diagram > pinout drawing — never a symbol or footprint). Upload it as an `--asset-type hero-image` to the wiki *and* call `emit_hero <url> <caption>` on the visualizer so the user can see it in the viewer header. Without a hero, the wiki datasheet index is unusable. See [adom-wiki SKILL.md](../adom-wiki/SKILL.md) and [human-ui-patterns SKILL.md](../human-ui-patterns/SKILL.md) for the full hero-image rule.
2. **Surface the artifacts to the user.** Summarize in chat:
   - Part name, manufacturer, document number, source URL
   - Hero image filename + reason it was picked
   - Section heading list (from the generated markdown) so the user can see what tabs will render
   - Diagram count with filenames + captions
   - Package list, key specs, any values the parser had to guess
2. **Confirm the visualizer is populated.** Every stage chip from `download` through `generate` should be green. Wiki-preview tabs (Overview / Pinout / Specs / …) should have content. If any are empty, fix before asking for approval.
3. **Ask explicitly with `AskUserQuestion`.** Two options, not a free-text prompt:
   - `Publish — everything looks right`
   - `Make changes first` → let the user describe what to fix, apply the fix, re-emit the updated section event, loop back to step 1 of this gate.
4. **Only on the first answer, run Step 7.** Never publish on anything less than an explicit "publish" click.

### What to do when the user asks for changes

- Keep the visualizer session open. Fix the markdown/diagrams/metadata in place. Re-`emit_section` for any tab whose content changed. Re-run the approval gate. Do not publish partially — it's all-or-nothing after approval.

## File layout

Same as `datasheet-parser`, with the added page mirror:

```
project-content/datasheets/<partname>/
├── <partname>.pdf
├── <partname>.md
├── <partname>.txt
├── metadata.json
├── pages/              # 300-DPI full-res renders — for crop operations
│   └── <partname>-*.png
├── pages-1500/         # ≤1500 px mirror — for Read-tool OCR
│   └── <partname>-*.png
└── <diagram>.png       # optimized crops
```

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Viewer chips never light up | Opened viewer URL with a stale `?session=` from a prior thread | Re-run Step 0: new session, new URL, close the old AV tab |
| `Read` fails with "image exceeds 2000px" | Skipped the Step 4a resize | Produce `pages-1500/` and Read from there |
| Viewer stuck on "Visual OCR" chip | Agent crashed mid-OCR, never emitted `ocr done` | If recoverable, resume parse. Otherwise `emit_done error` and restart with a fresh session |
| User clicks "Make changes first" and you re-publish anyway | Bug in your approval logic | Never publish without the explicit "Publish" answer from the gate. No exceptions |