| 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)
idf.py build
idf.py -p COM3 flash monitor
STM32
make
st-flash write firmware.bin 0x8000000
st-info --probe
RP2040
cmake --build build
picotool load build/firmware.uf2
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
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:
python scripts/camera_capture.py --session
read screenshots/capture_xxx.png
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:
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
- Fresh run required — Previous session's evidence invalid
- Complete cycle required — Build → Flash → Monitor
- Evidence required — Show output, not assumptions
- Visual evidence for GUI — Photo + monitor log
- State with evidence — Claim + supporting output
