The Software Over-specification Death Spiral

I see a common pattern with startups and teams I’ve advised or been a part of. I call it the Software Over-specification Death Spiral, or SODS for short.

It looks like this:

1. Product Manager (or CEO, Engineering Manager, etc) drafts up some sort of specifications or requirements for a new feature or product.
2. Product Manager (or CEO, Engineering Manager, etc) drafts up some sort of specifications or requirements for a new feature or product.
3. The requirements are handed over to the engineering team to implement.
4. The engineering team “implements” it, but gets some things wrong. One bucket of things that are prone to being wrong could be things that were so obvious that the PM thought they weren’t worth making explicit. Another bucket are corner or edge-cases that the PM didn’t think of.
5. The PM is surprised at this, and work has to be redone.
6. In an effort to prevent this in the future, both the PM and the engineering team agree that requirements need to be more detailed.
7. Surprise: despite the increased details in requirements, the engineering team still gets it wrong.

In each iteration of this loop, everyone agrees the requirements just need more details, but every time that happens, things are still wrong. What’s going on?

Breeding Code Monkeys

You’re breeding code monkeys, is what’s happening. Software is complex and malleable, and no set of specifications or requirements will ever be complete. There will always be behavior that requires some “filling in the blanks” at implementation time. The person doing the implementation needs to be able to either:

• Recognize when they should ask for clarification, or, preferably,
• Be able to fill-in-the-blanks correctly.

Counterintuitively, once you have this problem, the more you try to weed out ambiguity in requirements, the more likely you are cause the opposite effect of what you’ve want. Engineers turn off the part of their brain that they would use to think through product decisions, and become, essentially, “code monkeys” that just do what they’re told.

A Better Way

Does that mean you shouldn’t write specifications or requirements, or you should right less? Well, let’s not throw the baby out with the bathwater just yet. Specifications are important, but if you’re missing key pieces, they can make your problem worse.

At a high-level, when you’re building software, there are three questions to answer:

1. What the software does—requirements and behavior
2. Why it does what it does—actual problem it solves for its users
3. How it does what it does—the actual implementation

These three are all related. SODS occurs when engineers try to do #1 and #3 without understanding #2. As Simon Sinek would say, “you must start with why”.

It’s on both the PM and the engineering team to understand “the why”. A few suggestions for PMs (and engineers):

• Hire or worth with engineers who are inclined to understand the product, because they could be users themselves or because they have some other interest in the product space (or, as an engineer, try to help build products that you would use or that you find interesting).
• Make sure you explain why something is worth building (or, as an engineer, make sure you understand that, and if you don’t, ask).
• Push engineers to be involved in product decisions (or, as an engineer, try to be involved in various pre-implementation parts of the product lifecycle).
• Undertake other activities that help engineers build product intuition. Engineers can spend time with users, spend time understanding your products analytics, etc.
• If you really want to test whether an engineer is thinking about “the why”, have an engineer write the specifications for a feature of reasonable size, and then have the PM review them. If they can’t even attempt that, that’s usually a bad sign (though the worst sign of all is if they absolutely don’t want to even try).

Don’t fall victim to SODS.