Before writing code, make a decision

In previous posts I've insisted on a simple but uncomfortable idea: most problems in software projects don't appear in the code. They appear earlier, in unclear decisions, implicit assumptions, and compromises that are never explicitly discussed.

I keep insisting on the same things: stability, saying no in time, and reading the signals well before committing. And on how technical debt is, in reality, a business decision.

All of that points to the same conclusion: deciding well before writing code matters more than writing code fast.

The repeating problem

In practice, many projects start the same way:

• The problem isn't entirely clear.
• Success is defined ambiguously.
• Constraints are discovered along the way.
• Trade-offs appear under pressure, not in cold analysis.
• Scope expands without anyone explicitly deciding it.

When that happens, even good teams end up building things that work, but that no one wants to maintain. The cost appears later, in the form of technical debt, frustration, and loss of focus.

The need for a concrete tool

For years I've seen the same pattern: important conversations get postponed because "we'll address them later". That "later" almost always arrives when it's already expensive to change course.

The solution isn't more processes or more meetings. It's minimal structure applied at the right moment: before committing time, money, and technical capacity.

Project Clarity Canvas

That's why I created the Project Clarity Canvas: a one-page tool that forces answering, briefly and honestly, seven basic questions before building.

• What the real problem is
• How success is defined
• What constraints exist
• What trade-offs are being accepted
• What won't be built
• What risks are evident
• And, finally, what the decision is

If any of those parts can't be answered with clarity, that's already a signal. It's not a framework, heavy process, or promise of success; it's a minimal structure for making an informed decision.

The Canvas is also a filter

The Canvas isn't filled out as a formality. If you get to the end with vague fields, thin evidence, or unnamed risks, that's not a half-finished Canvas. That's the answer. The project isn't ready to execute.

Saying no to a project that shouldn't start is the most profitable technical decision you'll make. Every line of code written on top of an unclear decision multiplies the cost of rolling back. The Canvas turns that no into something defensible, not intuition.

How this works

The canvas works because it forces conversations that are normally postponed. Instead of "we'll address it later", it forces defining limits, constraints, and trade-offs before committing.

It doesn't replace technical design or discovery. It doesn't guarantee success. It's not for justifying decisions already made or for selling projects at all costs. It's for deciding before.

How this relates to what I've written

This canvas isn't an isolated product. It's a natural extension of everything I've been writing about in this blog.

Saying no requires criteria. Having clarity requires structure. Making engineering decisions requires tools that make them explicit.

This canvas is one of them. It documents the same discipline that lets us build well and turn down projects that compromise the quality of the result.

Writing code is relatively easy. Deciding what should exist is the hard part.

The Project Clarity Canvas doesn't promise to eliminate uncertainty. But it helps face it with judgment, before it becomes debt.

If you find it useful, you can download it here:

Project Clarity Canvas (PDF)One-page tool for evaluating projects before building them

Guide to using the Project Clarity Canvas (PDF)Brief document explaining when to use it, how to interpret it, and how to recognize healthy and alert signals