zevorn rt-claw Diagnose
Classify the failure first, then reduce it to the smallest command or code path that proves the issue.
Common Inputs
- Build logs from Meson, SCons, CMake, ESP-IDF, or Zephyr.
- QEMU boot output.
- Serial monitor logs from ESP32 hardware.
- Functional test or unit test output.
- Network, TLS, API proxy, Feishu, or Telegram errors.
- GitHub Actions or local CI output.
Workflow
- Identify the platform, command, branch, and changed files.
- Classify the failure:
- compile or link failure
- boot failure
- runtime crash or watchdog
- QEMU/network/API failure
- test assertion failure
- style, DCO, or secret-check failure
- Extract the first meaningful error, file, line, symbol, or backtrace frame.
- Cross-check recent changes with
git diffand relevant source files. - Form one primary hypothesis and the narrowest verification command.
- Fix only the implicated subsystem, then rerun the narrowest useful check.
- If uncertain, list two or three possible causes ranked by evidence and name the next command that would distinguish them.
Common Patterns
| Pattern | Likely cause | Next check |
|---|---|---|
undefined reference to claw_* |
missing source in Meson or wrong feature guard | check meson.build includes the .c file |
implicit declaration of function |
missing include or wrong public header | check include order and exported headers |
redefinition of macro |
claw_config.h vs generated config conflict |
check config guards and Meson options |
multiple definition of |
function body in header without static inline |
move implementation to .c or mark inline |
FreeRTOS/RT-Thread/Zephyr include inside claw/ |
OSAL boundary violation | move RTOS dependency to osal/<rtos>/ |
DHCP timeout or dhcp_fine_tmr |
QEMU network setup issue | inspect QEMU -nic options |
DNS resolution failed |
no DNS in QEMU or wrong network config | use scripts/api-proxy.py when needed |
TLS handshake failed or esp_tls |
ESP32 QEMU TLS limitation | route through scripts/api-proxy.py |
HTTP 503 |
API endpoint, rate limit, or token problem | verify endpoint and credentials outside commits |
Stack overflow or pxCurrentTCB |
task stack too small | inspect task creation stack sizes |
Data Abort or Prefetch Abort |
NULL pointer or bad memory access | rerun QEMU with GDB=1 |
Guru Meditation |
ESP-IDF crash, watchdog, stack, or allocation issue | decode backtrace and inspect task state |
| watchdog timeout | blocking call, deadlock, or undersized task stack | check mutexes and long blocking calls |
Feishu no connection detected |
WebSocket endpoint or token issue | verify app ID/secret and endpoint |
Telegram HTTP 503 |
bot token, API, or rate limit issue | verify with Telegram getMe |
connection reset by peer |
TLS version or proxy issue | check whether api-proxy.py is running |
QEMU boot test failed |
boot regression or network-dependent boot path | inspect boot banner and test profile |
scripts/check-patch.sh failure |
style, line length, comments, or whitespace | rerun staged style check |
| DCO failure | missing Signed-off-by |
recommit with git commit -s |
Rules
- Do not infer missing environment details. Mark them as missing.
- Do not commit credentials from logs,
sdkconfig, environment dumps, or local config files. - Do not broaden a fix to unrelated platforms without evidence.
- For bugs, add or update regression coverage when the current test structure can express the failure.