ws-ESP32-S3-CAM: Command for Claude Code

Safe feature-dev loop for ESP32-S3 cry-detect-01

Use this flow when adding a new subsystem (new task, new driver, new Kconfig symbol). Every crash we've had in this project came from skipping one of these checks. Usage: /safe-dev <what-you're-adding>.

Principle: change one thing, verify, then change the next

The ESP32-S3 + native USB-JTAG makes iteration slow because:

• Every serial-monitor open briefly toggles DTR/RTS → chip resets
• A bootloop takes ≥5 s per cycle; multi-feature breakage is hard to bisect
• Assert/panic backtraces require addr2line — only useful if you saved the .elf from the exact build that crashed

So: add one subsystem, flash, verify, commit, then add the next.

Pre-flash checklist

Before every flash, tick these:

1. New Kconfig enabled? Check if it changes stack sizes / requires companion symbols.

   • CONFIG_FREERTOS_USE_TRACE_FACILITY=y → adds per-TCB bookkeeping; bump small task stacks
   • CONFIG_FATFS_LFN_HEAP=y → fopen of long names consumes extra heap; SD open can slow
   • Any new driver component (e.g. driver/temperature_sensor.h) → often pulls in event-loop handlers; do NOT install inside another driver's callback

2. New task? Start it with 6 KB stack minimum unless you have a reason to go smaller. Add to WDT if it runs > 1 Hz. Pin to core 0 (Wi-Fi/lwIP on 0; model inference on 1).

3. New callback on event loop? Anything in esp_event_loop_run_task context must be non-blocking. Do not:

   • call fopen/fwrite/SD I/O
   • take long-held mutexes (sd_logger, metrics, etc.)
   • call into sd_logger_ntp_sync_marker which opens+closes files

   Instead: signal a worker task via a queue/semaphore.

4. New mutex? Write down the lock order on paper. This project has mutexes in sd_logger, web_ui, event_recorder, metrics_logger, noise_floor. A handler that takes two of them in the wrong order will deadlock.

5. New heap allocation > 1 KB? Use heap_caps_malloc(n, MALLOC_CAP_SPIRAM) not stack, not internal RAM. Our internal DRAM is ~250 KB and every task competes.

6. Feature flag in Kconfig? Add an CONFIG_CRY_<X>_ENABLED symbol defaulting OFF until verified. That way rollback is sed one line, not revert five files.