Silicon-Grade Discipline

Overview

Software bugs ship a patch. Hardware bugs ship a respin, or a recall, or a dead board on a bench you can't reach. That asymmetry changes how you write code in this domain: correctness is not negotiable against speed, because the cost of wrong is measured in mask sets and weeks.

Core principle: A failure must be loud, a check must be honest, and a fix must address the root cause. The most dangerous output in this domain is a green checkmark over a real defect.

When to Use

• Writing or reviewing code that drives, verifies, or generates hardware
• Tempted to add a flag that makes a failing check pass
• Tempted to add recovery scaffolding for a failure mode you haven't diagnosed
• Deciding between panic/assert and returning an error
• Deciding how much test coverage is enough

This skill is the shared backbone; the domain skills (hdl-module-design, tapeout-precheck, differential-verification, and others) lean on it.

Failures Should Fail

Never add a knob that converts a real failure into a pass. No ERROR_ON_DRC=false, no --skip-lvs, no if (mismatch) verdict = pass, no "temporarily" commented-out assertion. Those don't fix the problem; they hide it and then ship it.

• A failing check means the design or the code is wrong. Fix the thing being checked.
• A legitimate exception is explicit, recorded, and granted by the authority that owns the rule (the foundry, the spec), with its rationale written down. It is never a flag you flipped to hit a date.
• Trust the logs. Read what the tool actually reported. "0 errors" from a run that skipped the check is worse than a red failure, because it lies.

Don't Over-Engineer Recovery Hatches

Resist building preemptive save-on-failure, retry-until-it-works, or rollback scaffolding around a failure you haven't understood. That machinery hides the bug, adds surface area, and convinces you the system is robust when it is actually papering over a real defect.

• Diagnose the root cause first. A retry loop around a corruption just corrupts more slowly.
• Trust the logs and the crash. A clean fault that tells you where it broke is more valuable than a system that limps past the break.
• Build the recovery you actually need, once you understand the failure, not the recovery you imagine you might need.

Don't Panic; Return Errors

Reserve panic/abort/unwrap-on-error for genuinely impossible states (an invariant the type system can't express, which if violated means memory is already corrupt). For everything that can fail in normal operation (bad input, a device that didn't respond, a parse that failed), return a typed error and let the caller decide.

• Library code returns typed errors (thiserror-style). User-facing layers render them nicely (color-eyre-style). Structured logging (tracing-style) records the context.
• A panic in a verification farm or a bring-up tool takes down the run and loses the diagnostic. An error propagates the context you need.

Test Like It's Going To Silicon

Because it is.

• Exhaustive coverage per component, not just the happy path through the top level. Sweep parameters and boundaries.
• Test files mirror the source layout so every unit's test is findable.
• Cover the failure paths: assert that bad input actually errors, that validation actually rejects.
• Logic lives in the library so it's testable without a process; the CLI/daemon is a thin consumer.

Red Flags

Midstall House Style

• These rules recur across Aegis, Harbor, Heimdall, Ferrite, and the rest, because everything here is heading toward real hardware.
• No design docs for their own sake; keep reasoning in-conversation and fix the root cause.
• No em dashes, no emoji, no slang. Plain, direct, honest about what works and what doesn't.