I got tired of not having a single good place to point people.
Not to a blog post that would be half-stale in a year. Not to a book they'd have to read first. Just somewhere to open mid-conversation and say - yeah, this is what's happening, here's what it usually leads to, here's what we should probably do.
So I built it myself: https://thehardparts.dev
What's in it
The site has four sections, all cross-linked. A red flag usually precedes a failure mode, which usually forces a decision, which usually needs a playbook - so I tried to make those connections explicit rather than leaving them implicit the way most writing does.
Failure Modes are named patterns for how software work goes wrong - not generic "communication is hard" content, but specific shapes with a beginning, a middle, and a set of early signals. The Friendly Rewrite, The Hero Trap, The Invisible Deadline. The goal is that you can open one during a retro and say "this is what's happening here."
Red Flags are the earlier signals - the things that show up before the failure has obviously arrived. Nobody Can Explain This Module Simply. Ownership Is Claimed but Not Visible. People Avoid Touching Certain Areas. Each entry tries to get you from "something feels off" to "here's what to inspect next."
Tech Decisions are the trade-offs people keep arguing about as if one side were universally right. Instead of best practices, I wanted honest ledgers: what the choice is really about, what each side secretly costs, who pays it, and what bad reasons usually drive the decision in practice.
The Engineering Playbooks are operational guides for recurring situations - with explicit judgment calls, pitfalls, and signals that it's actually working. Not "be more collaborative" advice. Things like Run a Phased Migration, Start a Rewrite Safely, Build a Practical Rollback Strategy.
Why I made it
I kept finding myself in conversations where the pattern was obvious to me but hard to name clearly enough to be useful. Having a name and a structure for something changes the conversation - you can say "this is The Invisible Deadline" instead of spending twenty minutes establishing that a deadline exists but nobody will say it out loud.
I also wanted something that got more useful over time rather than going stale. A blog post about microservices from 2019 is mostly noise now. A trade-off ledger for the same decision, kept honest, stays relevant.
Still adding entries. Would love to know which ones feel immediately true, which feel thin, and what patterns you think are missing.
Top comments (0)