debug-hardware

Diagnose hardware and firmware issues using evidence-first debugging with datasheets and register maps.

Updated Nov 1, 2024
One-click install
npx skills add https://github.com/mlorentedev/dotfiles --skill debug-hardware-mlorentedev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug-hardware
Source: https://github.com/mlorentedev/dotfiles/tree/main/harness/skills/debug-hardware
Command: npx skills add https://github.com/mlorentedev/dotfiles --skill debug-hardware-mlorentedev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Hardware and firmware bugs are notoriously hard to fix because engineers often guess at causes instead of reading the actual hardware truth — register reset values, timing diagrams, and reference implementations. This Skill applies a disciplined, evidence-first debugging method specialized for hardware domains. ## Core Features & Use Cases - Hardware Evidence Sources: Directs you to consult datasheets, register maps, timing diagrams, protocol specs, and vendor reference implementations before forming any hypothesis. - Common Pitfall Prevention: Flags classic hardware mistakes such as assuming register defaults, changing multiple registers at once, ignoring setup/hold times, and guessing endianness. - Use Case: A camera sensor returns garbled frames. Instead of randomly tweaking registers, you compare observed register values against the datasheet reset values and the vendor's known-good configuration, change one register per test, and verify after each change. ## Quick Start Use the debug-hardware skill to troubleshoot why my embedded sensor returns incorrect register values after initialization.

Frequently Asked Questions about debug-hardware

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug hardware register configuration issues?

Read the datasheet for actual register reset values rather than assuming defaults, then compare observed register values against expected ones. Change only one register per test and verify the result after every change to isolate the cause.

How to troubleshoot firmware and embedded sensor problems?

Gather concrete evidence first: register values, signal traces, and error codes, then compare against the vendor reference implementation or known-good configuration. Form a single hypothesis from that evidence before attempting any fix.

What is evidence-first debugging for hardware?

Evidence-first debugging means never guessing: you form one hypothesis from observed data such as register reads and timing measurements, apply the minimal fix, and verify after every change. The method comes from the systematic-debugging skill, specialized here for hardware.

Why does my device behave differently than the datasheet suggests?

Common causes include assuming register defaults instead of checking documented reset values, ignoring setup and hold timing requirements, wrong clock domains, or incorrect byte order. Verify endianness and timing against the protocol specification.

When should I use systematic-debugging instead of a hardware-specific approach?

Use systematic-debugging for the general debugging process and Iron Rule method in any domain. Use the hardware specialization when the evidence sources are datasheets, register maps, timing diagrams, and signal traces rather than software logs.