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.

We've talked about stability as an engineering decision. About why saying no is a technical responsibility. About what signals make a project worth it. About 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.

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.

If we talk about saying no, we need criteria. If we talk about clarity, we need structure. If we talk about engineering decisions, we need tools that make them explicit.

This canvas is one of them. It documents the same discipline that allows building with enterprise standards and rejecting projects that compromise quality.

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