silicon-grade-discipline

name	silicon-grade-discipline
description	Use when writing hardware, firmware, verification, or tooling code that will reach real silicon, and you face a tradeoff between shipping fast and shipping correct; covers failures-should-fail, no over-engineering, no-panic, and test coverage

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

Thought	Reality
"I'll add a flag to skip this check for now"	That flag ships a known defect. Fix the check's subject.
"Let me add a save/retry in case it fails"	Diagnose first. Recovery for an undiagnosed failure hides it.
"I'll panic here, it shouldn't happen"	If it can happen in normal operation, return an error.
"0 errors printed, we're good"	Confirm the check actually ran. Trust the logs, not the absence.
"Top-level test passes, that's enough"	Cover each component and its failure paths.
"It's close enough"	For silicon, close enough is a respin.

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.