Correct EEPROM soft-brick record: partial write on undersized U7 kills enumeration

Hardware bring-up correction (Dennis, 2026-08-22): writing the FT2232H product
string to the undersized 93LC46B (U7) does NOT harmlessly fail — the partial,
mirrored write lands a checksum-valid-but-garbage config, and the FT2232H then
FAILS USB enumeration entirely (dead silent, no dmesg attach). It does NOT fall
back to ROM defaults; only a blank/checksum-invalid EEPROM does. The earlier
claim that "a bad EEPROM always falls back and still enumerates" was WRONG.

Recovery (confirmed working): power on with U7 CLK shorted to GND so the FT2232H
can't read a valid config -> forces ROM defaults -> enumerates -> then erase U7.

Updated REVIEW.md, TODO.md, the flash-re-bba-rb skill (do-not-program warning +
recovery, native-Linux troubleshooting), and flash_ftdi_eeprom.py comments/help
to state the soft-brick reality. The script already refuses the write on
mirroring detection; --force now documented as "reproduce the soft-brick".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.claude/skills/flash-re-bba-rb/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flash-re-bba-rb
-description: Use when flashing the re-bba-rb board (GC BBA FPGA replacement) — programming the iCE40UP5K bitstream with iceprog and/or the FT2232H EEPROM product string ("re-BBA-rb") with pyftdi, from inside the WSL2 devcontainer. Covers USB passthrough prerequisites, best-seed bitstream selection, sudo/libusb access, and backup-first EEPROM programming.
+description: Use when flashing the re-bba-rb board (GC BBA FPGA replacement) — programming the iCE40UP5K bitstream with iceprog from inside the devcontainer (native-Linux or WSL2 host USB passthrough). Covers USB prerequisites, best-seed bitstream selection, sudo/libusb access. WARNING: on V1 the FT2232H EEPROM (U7 93LC46B) is undersized and writing the product string SOFT-BRICKS enumeration — the skill documents why not to, and the CLK-to-GND recovery.
 ---
 
 # Flashing the re-bba-rb board
@@ -62,34 +62,52 @@ image.
 `ICEPROG=/path/to/iceprog` overrides the binary if needed; the container's is on
 `PATH`.
 
-## Step 2 — Program the FT2232H EEPROM (optional, cosmetic)
+## Step 2 — FT2232H EEPROM product string — ⚠️ DO NOT DO THIS ON V1
 
-Only after Step 1 verifies. This changes **descriptor strings only** — VID/PID
-`0403:6010` and the dual-channel config are preserved, so `iceprog` and the
-channel-B UART keep working. Values live in `hardware/re-bba-rb/flash_ftdi_eeprom.py`
-(and mirror `hardware/re-bba-rb/ftdi_eeprom.conf`): manufacturer `hashru`,
-product `re-BBA-rb`, serial `RBBARB001`.
+**On the re-bba-rb V1 board, writing the EEPROM product string SOFT-BRICKS the
+FT2232H.** U7 is a 93LC46B (128 B), too small for the FT2232H (which needs a
+93LC56B / 256 B). A string write lands a partial, checksum-valid-but-garbage
+config; the FT2232H reads it at power-up and **fails USB enumeration entirely —
+dead silent, no `dmesg` attach.** It does NOT fall back to ROM defaults (only a
+BLANK / checksum-invalid EEPROM does). Confirmed on hardware 2026-08-22.
 
-```bash
-# Dry-run first: dumps a backup (eeprom-backup.bin) + prints the diff, no write.
-sudo /opt/venv/bin/python hardware/re-bba-rb/flash_ftdi_eeprom.py
+`flash_ftdi_eeprom.py` **detects the mirrored/undersized chip and refuses the
+write** — leave it that way. There is no way to program the string on V1; it
+needs a 93LC56B at U7 (a future rev). The board is fully functional without it:
+it enumerates on ROM defaults (`Dual RS232-HS`, `0403:6010`) and iceprog + the
+channel-B UART work normally.
 
-# If the diff looks right, commit:
-sudo /opt/venv/bin/python hardware/re-bba-rb/flash_ftdi_eeprom.py --commit
-```
-The script always writes `hardware/re-bba-rb/eeprom-backup.bin` before staging
-changes. After `--commit`, re-plug / re-attach USB so the host re-reads
-descriptors; the unit then shows as **re-BBA-rb**.
+### Recovery — if U7 ever gets a bad config written (soft-brick)
 
-To restore the backup later, use `pyftdi`/`ftdi_eeprom` to write
-`eeprom-backup.bin` back (raw image).
+Symptom: the FT2232H disappears from USB completely (no `dmesg` on plug) even
+though it's powered (3.3 V on VCC/VPHY/RESET#/DP all present). Fix — the classic
+FTDI EEPROM recovery, done on the V1 unit and confirmed working:
+
+1. **Power the board on with U7's CLK pin shorted to GND.** This corrupts the
+   EEPROM read so the FT2232H can't load the bad config → it enumerates on ROM
+   defaults (`0403:6010`).
+2. Release the short and immediately blank U7:
+   ```bash
+   sudo /opt/venv/bin/python hardware/re-bba-rb/flash_ftdi_eeprom.py --erase --commit
+   ```
+   (On the mirrored chip pyftdi's 256-byte verify trips even though the 0xFF
+   writes land — the script loops and checks actual content, so ignore the
+   per-attempt verify warnings; it reports "fully blank" when done.)
+
+To restore a saved backup instead, write `eeprom-backup.bin` back as a raw image.
 
 ## Troubleshooting
 
-- **`/dev/bus/usb` empty / device object is `None`** → not attached to WSL2. Run
-  `.devcontainer/attach-icebreaker.ps1` (admin) on Windows; check
-  `usbipd list` shows the FT2232H `Attached`. If the WSL2 kernel lacks usbfs,
-  `/dev/bus/usb` won't populate at all — update WSL (`wsl --update`).
+- **`/dev/bus/usb` empty / device object is `None`** → the FT2232H isn't on the
+  host bus (the container's `/dev/bus/usb` mirrors the host live). On a **native
+  Linux host** (e.g. Arch — Docker directly): `lsusb | grep 0403` on the host; if
+  missing, re-plug the cable. On a **Windows/WSL2 host**: run
+  `.devcontainer/attach-icebreaker.ps1` (admin) and check `usbipd list` shows it
+  `Attached`.
+- **Powered but totally silent on plug (no `dmesg` attach at all)** → most likely
+  a soft-bricked FT2232H EEPROM (see Step 2 recovery) if the EEPROM was ever
+  written; otherwise a severed USB power/data via from the board repair. A blank
+  EEPROM does NOT cause this — a *partial* write does.
 - **`Permission denied` / `LIBUSB_ERROR_ACCESS`** → run the command under `sudo`
   (the nodes are root-owned). Both `iceprog` and the pyftdi script need it.
 - **`iceprog` can't find the device but `pyftdi` sees it (or vice-versa)** → a
@@ -106,11 +124,12 @@ To restore the backup later, use `pyftdi`/`ftdi_eeprom` to write
 
 ## Guardrails
 
-- **Bitstream before EEPROM** — the EEPROM string is cosmetic and never worth
-  risking before the board is functionally proven.
+- **Do NOT program the EEPROM string on V1 — it soft-bricks the FT2232H** (U7 is
+  an undersized 93LC46B; see Step 2). The script refuses by design; do not
+  `--force` it. Recovery is CLK-to-GND at boot + `--erase`.
 - **Never change VID/PID** in the EEPROM — `iceprog` and D2XX look for
   `0403:6010`. The script/conf keep it; don't override.
 - **Always flash the swept best-seed** `.bin`, never a no-`--seeds` seed-1 build
   (capture timing fails on it).
-- Keep the EEPROM backup (`eeprom-backup.bin`) until the string change is
-  confirmed good on the host.
+- A **blank** EEPROM is the correct, working state on V1; only a *partial* write
+  is dangerous.