Embedded fault debug
Use when embedded firmware crashes, traps, faults, resets unexpectedly, jumps to default handlers, corrupts stack, or executes invalid instructionsFrom its SKILL.md
npx -y skills add easyzoom/aix-skills --skill embedded-fault-debugAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
SKILL.md
4.2 KB, 936 tokens by cl100k_base, as published. Nobody here has run it
Embedded Fault Debug
Overview
Use this skill to preserve crash evidence and find the first failing instruction. The agent should read architecture-specific fault state before reset, map addresses to symbols, and separate root cause from secondary symptoms.
When To Use
Use this skill when:
- Firmware hits HardFault, BusFault, UsageFault, trap, illegal instruction, default handler, watchdog reset, assert, or panic.
- The board resets unexpectedly or hangs after a repeatable action.
- The user has a register dump, fault log, crash PC, stack dump, watchdog event, or GDB backtrace.
Do not use this skill when the target cannot yet connect or flash; use mcu-flashing-debug first.
First Questions
Ask for:
- Architecture/chip family and toolchain.
- Exact symptom and whether it is reproducible.
- Register dump, backtrace, fault/trap registers, assert log, or reset reason.
- ELF/MAP file that matches the running image.
- Whether the target has been reset since the fault.
Workflow
-
Preserve state. Do not reset or reflash until fault registers, PC, LR/RA, SP, and stack frame are captured.
-
Confirm image-symbol match. Ensure the ELF/MAP file matches the firmware currently running on target.
-
Identify the faulting address. Map PC, exception return address,
mepc, stacked PC, or return address to a symbol and source line. -
Classify the cause. Separate invalid memory access, illegal instruction, stack overflow, alignment, bus/peripheral access, watchdog, assert, and default handler cases.
-
Walk backward to the first bad state. Inspect caller, input pointers, stack bounds, interrupt context, DMA/cache interactions, and recent initialization.
-
Add a focused verification. Use a watchpoint, assertion, guard pattern, stack watermark, or minimal repro to prove the suspected cause.
Architecture Notes
Cortex-M
Read SCB fault registers before reset:
CFSR = 0xE000ED28
HFSR = 0xE000ED2C
MMFAR = 0xE000ED34
BFAR = 0xE000ED38
Decode stacked r0-r3, r12, lr, pc, and xpsr from MSP or PSP.
RISC-V
Read:
mcause, mepc, mtval, mtvec, mstatus, sp
Check whether mcause is interrupt or exception, and map mepc to source/disassembly.
8051
Use available evidence:
- Reset reason register if the derivative provides one.
- Stack pointer and internal RAM pressure.
- ISR vector selection and default handler loops.
- Watchdog configuration.
- GPIO heartbeat or serial breadcrumbs around suspected code.
Common Root Causes
- Stack overflow or ISR stack pressure.
- Null/corrupt function pointer.
- Wrong vector table, trap vector, or interrupt number.
- Accessing peripheral before clock/reset release.
- DMA writing outside buffers.
- Cache coherency issue on cache-enabled MCUs.
- Compiler target flags not matching core features.
- Watchdog not serviced during long init.
- Bootloader/app offset mismatch.
Verification
Before claiming a fault is understood:
- State the matched ELF/MAP and running firmware identity if known.
- Report faulting PC/address and mapped symbol/source.
- Report architecture-specific fault registers or explain why unavailable.
- State the suspected root cause and the evidence linking it to the fault.
- State the next minimal verification step, such as watchpoint, stack watermark, or assertion.
Common Failures
- Resetting immediately and losing the only useful fault state.
- Trusting a backtrace when the ELF does not match flashed firmware.
- Fixing the line where the fault occurred instead of the earlier corruption.
- Ignoring interrupt context, stack selection, or DMA/cache side effects.
- Treating watchdog reset as a generic crash without reading reset reason.
Example
User:
程序跑一会儿就进 HardFault。
Agent:
- Asks for chip, ELF, register dump, CFSR/HFSR, stacked PC, and whether reset happened.
- Maps stacked PC to source.
- Checks stack bounds, caller, interrupt context, and invalid memory access evidence.
- Suggests a focused watchpoint or stack watermark before changing code.
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.
Gives 0 of the 12 instructions most debug triage skills give in 936 tokens
Counted across 1,020 of the 1,639 authors here whose files we hold, read 2026-09-06
- Find root cause before attempting any fixin 134 of 1020, across 118 files
- Create a failing test case before implementing a fixin 109 of 1020, across 95 files
- Read error messages and stack traces completelyin 102 of 1020, across 88 files
- Reproduce the issue consistently before investigatingin 90 of 1020, across 77 files
- Make the smallest possible change to test a hypothesisin 90 of 1020, across 76 files
- Trace data flow backward to find the sourcein 84 of 1020, across 70 files
- Form a single hypothesis before testingin 78 of 1020, across 64 files
- Implement only one fix at a timein 76 of 1020, across 63 files
- Question the architecture if three fixes failin 73 of 1020, across 59 files
- Add diagnostic instrumentation at component boundariesin 68 of 1020, across 56 files
- Compare broken code against working examplesin 68 of 1020, across 57 files
- Write a regression test before applying the fixin 62 of 1020, across 55 files
Said here and by no other author read
- Capture fault registers before resetting the target
- Verify ELF file matches the running firmware
- Map faulting address to source code line
- Classify fault cause based on register state
- Inspect stack bounds and interrupt context
- Trace backward to identify initial corruption
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.