embedded-verification

name	embedded-verification
description	Use when about to claim embedded work is complete - requires build-flash-monitor output evidence, NO claims without fresh verification

Embedded Verification Before Completion

Overview

Claiming firmware is complete without hardware verification is dishonesty.

Core principle: Evidence before claims, always.

Announce at start: "I'm using the embedded-verification skill to collect build-flash-monitor evidence before claiming completion."

---

The Iron Law

NO COMPLETION CLAIM WITHOUT BUILD-FLASH-MONITOR OUTPUT

---

The Gate Function

digraph verification_gate {
    "Status claimed?" [shape=ellipse];
    "IDENTIFY: What command proves this?" [shape=box];
    "RUN: Build-Flash-Monitor (fresh)" [shape=box];
    "READ: Full output" [shape=box];
    "VERIFY: Evidence confirms claim?" [shape=diamond];
    "STOP: Run verification first" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
    "State actual status with evidence" [shape=box];
    "State claim WITH evidence" [shape=box];
    "Completion claimed" [shape=doublecircle];

    "Status claimed?" -> "IDENTIFY: What command proves this?";
    "IDENTIFY: What command proves this?" -> "RUN: Build-Flash-Monitor (fresh)";
    "RUN: Build-Flash-Monitor (fresh)" -> "READ: Full output";
    "READ: Full output" -> "VERIFY: Evidence confirms claim?";
    "VERIFY: Evidence confirms claim?" -> "STOP: Run verification first" [label="no - no evidence"];
    "VERIFY: Evidence confirms claim?" -> "State actual status with evidence" [label="partial - some evidence"];
    "VERIFY: Evidence confirms claim?" -> "State claim WITH evidence" [label="yes - confirmed"];
    "State claim WITH evidence" -> "Completion claimed";
}

---

Required Evidence by Claim Type

Claim	Required Evidence	Command
Driver compiles	idf.py build output: "Project build complete" + exit 0	idf.py build
Driver flashed	Monitor output: "Hash of data verified"	idf.py -p PORT flash
LCD works	Monitor log: "LCD initialized" + screen photo	idf.py -p PORT flash monitor
Sensor reads	Monitor log: "Sensor value: X" timestamps	idf.py -p PORT flash monitor
Wi-Fi connects	Monitor log: "Connected to AP" + IP address	idf.py -p PORT flash monitor
Bug fixed	Monitor log: No crash/assert + expected behavior	idf.py -p PORT flash monitor

---

Verification Commands (Platform-Specific)

ESP-IDF (ESP32)

# Complete verification cycle
idf.py build
idf.py -p COM3 flash monitor

# Expected output for success:
# Project build complete. 100% complete.
# Hash of data verified.
# I (100) LCD: LCD initialized successfully

STM32

make
st-flash write firmware.bin 0x8000000
st-info --probe

# Expected output:
# Build complete
# Flash written successfully
# Chip detected

RP2040

cmake --build build
picotool load build/firmware.uf2
# USB CDC monitor

# Expected: UF2 written, USB serial active

---

The Verification Process

Step 1: Identify Verification Command

Ask: "What command proves this works?"

Driver compiles → idf.py build
Driver flashes → idf.py flash
Hardware works → idf.py flash monitor

Step 2: Run Fresh Verification

IMPORTANT: Fresh run, not cached results.

idf.py build flash monitor

Do NOT trust:

• Previous session's output
• "Should work now" without running
• IDE build button (different from CLI)

Step 3: Read Full Output

idf.py build flash monitor
# Capture ALL output
# Look for: errors, warnings, success markers

Key markers to check:

• Build: "Project build complete" + 0 errors
• Flash: "Hash of data verified"
• Monitor: Expected log messages, no crashes

Step 4: Verify Against Claim

Expected Log	Claim Supported
"LCD initialized"	LCD driver working
"Sensor value: X"	Sensor reading data
"Connected to AP"	Wi-Fi functional
No crash/assert	Stable operation

Step 5: State Status with Evidence

If evidence confirms claim:

"Build complete. Flash verified. Monitor shows 'LCD initialized'. 
LCD driver verified working."

If evidence partial:

"Build passes. Flash fails with 'timeout waiting for ACK'.
Driver NOT working. Issue: [specific error]."

If no evidence:

"Cannot claim completion. No verification run. 
Run: idf.py build flash monitor"

---

Monitor Output Analysis

Success Patterns

LCD Driver Success:
  - "I (xxx) LCD: LCD initialized successfully"
  - "I (xxx) LCD: LCD ID: 0x7789" (ST7789)
  - No "E (xxx) LCD:" error logs
  
Sensor Success:
  - "I (xxx) IMU: Accel X=xxx Y=xxx Z=xxx"
  - Regular sensor log timestamps
  - No "E (xxx) IMU:" error logs
  
Wi-Fi Success:
  - "I (xxx) wifi: Connected to AP [SSID]"
  - "I (xxx) wifi: Got IP: 192.168.x.x"
  - No "E (xxx) wifi:" error logs

Failure Patterns

LCD Failure:
  - "E (xxx) LCD: SPI transmit failed"
  - "E (xxx) LCD: Timeout waiting for response"
  - "assert failed: lcd_init"
  
Sensor Failure:
  - "E (xxx) IMU: I2C read failed"
  - "E (xxx) IMU: Device not found at address 0xXX"
  
System Failure:
  - "Guru Meditation Error"
  - "Core 0 register dump"
  - "assert failed"

---

Visual Evidence (GUI Components)

For LCD/display verification:

# Capture screen
python scripts/camera_capture.py --session

# Expected:
# - Screenshots saved to screenshots/
# - Visible LCD content matching expected

# Analyze
read screenshots/capture_xxx.png
# Check: Layout, color, text visible

Required for LCD claims:

• Monitor log: "LCD initialized"
• Screen photo: Visible content

---

Common Failures

Claim	Reality Check	Action
"Should compile now"	RUN idf.py build, show output	No guessing
"Driver should work"	RUN flash monitor, show logs	Evidence required
"LCD initialized"	Show monitor log + screen photo	Double evidence
"Tested on breadboard"	Show THIS session's monitor output	Fresh evidence
"Linter passed"	Linter ≠ compiler ≠ hardware	Run full cycle
"Previous session verified"	Previous ≠ current	Run fresh now

---

Rationalization Table

Excuse	Reality
"Should work now"	Run verification. Show output.
"I tested earlier"	Previous session ≠ current state. Run fresh.
"Build passed so it works"	Build ≠ Flash ≠ Monitor. Full cycle required.
"Mock tests passed"	Mock ≠ Hardware. Hardware verification required.
"Visual inspection looks right"	Photo required for GUI claims.
"It's just a small change"	Small changes can break. Verify.

---

Red Flags - STOP

If you think:

• "Should work now" without running commands
• "I verified earlier today" (not fresh)
• "Build passed, should be fine"
• "Skip monitor, save time"
• "Linter/typecheck passed"
• "Visual inspection sufficient"

STOP. You are rationalizing. Run fresh verification.

---

Checklist (Create TodoWrite)

Before claiming completion:

• Build command identified
• Build run fresh
• Build output: "Project build complete" + exit 0
• Flash command identified
• Flash run fresh
• Flash output: "Hash verified"
• Monitor command identified
• Monitor run fresh
• Monitor output: Expected logs present
• Monitor output: No crashes/asserts
• Visual evidence captured (for GUI)
• Status stated WITH evidence

---

Integration

Previous skill: embedded-tdd (tests pass)

This skill: Collect build-flash-monitor evidence

After verification: State completion WITH evidence

---

Platform-Specific Verification

Windows (PowerShell)

idf.py build
idf.py -p COM3 flash monitor
# Use ; if($?) { } for chaining

Linux/macOS (Bash)

idf.py build && idf.py -p /dev/ttyUSB0 flash monitor

---

Serial Monitor Analysis Script

python scripts/serial_monitor.py -p COM3 -d 60 --json

Output: Structured JSON for AI analysis

{
  "timestamp": "2026-04-13T14:30:00",
  "logs": [
    {"level": "I", "tag": "LCD", "message": "LCD initialized successfully"},
    {"level": "I", "tag": "LCD", "message": "LCD ID: 0x7789"}
  ],
  "errors": [],
  "crashes": false
}

---

Key Principles

1. Fresh run required — Previous session's evidence invalid
2. Complete cycle required — Build → Flash → Monitor
3. Evidence required — Show output, not assumptions
4. Visual evidence for GUI — Photo + monitor log
5. State with evidence — Claim + supporting output