Implementing STUPID.md: A New Standard for Documenting Codebase Workarounds

I’m with STUPID ⤴️

Developer Gesslar proposes the STUPID.md standard to document hacks necessitated by external upstream failures. This system formalizes the documentation of ‘Fragility as Infrastructure’ that often costs teams days of debugging time.

Why This Matters

In professional software development, ideal models assume dependencies and toolchains function idiomaticly, but reality often requires ‘idiotic’ incantations to achieve cross-platform functionality. Without a dedicated STUPID.md file, future maintainers frequently remove these necessary workarounds during cleanup passes, inadvertently breaking the build and incurring significant costs to rediscover the original upstream failure.

Key Insights

• The STUPID.md file documents the cost of workarounds rather than adjudicating blame for external failures (Gesslar, 2026).
• Fragility as Infrastructure represents purposeful blocks of code that look wrong but are required to fix upstream tool chain errors.
• A mandatory ‘Fixed’ section tracks resolved issues to celebrate when upstream tools eventually reconcile with reality.
• Tauri developers utilize specific environment flags to circumvent WebKit DMABUF renderer crashes on X11 and NVIDIA systems.
• Each entry requires a specific file and line reference (path/to/file:line) to ensure the workaround is verifiable by future contributors.

Working Examples

An example entry for a STUPID.md file documenting a specific upstream workaround.

### Blanket-disable WebKit's DMABUF renderer on Linux
`src-tauri/src/lib.rs:71-83`
The WebKit DMABUF renderer crashes on X11 + NVIDIA. We set
`WEBKIT_DISABLE_DMABUF_RENDERER=1` before Tauri spawns any threads,
because `std::env::set_var` is `unsafe` for exactly that reason.
See: [tauri-apps/tauri#8541](https://github.com/tauri-apps/tauri/issues/8541)

Practical Applications

• Use case: Documenting OS-specific workarounds for Debian and Ubuntu parity when upstream toolchains diverge.
• Pitfall: Removing a ‘weird’ code pattern during an architectural cleanup without checking STUPID.md, resulting in a broken production build.
• Use case: Moving resolved workarounds to a ‘Fixed’ section once an upstream PR or bug report is officially closed.
• Pitfall: Venting about upstream failures without providing the required file reference or actionable technical detail.

References:

• https://dev.to/gesslar/im-with-stupid-g8m