Most technical debt isn’t actually technical

Why onboarding decisions matter more than code. Technical debt is often framed as a technical problem. We talk about code quality, rushed architecture, or wrong tooling decisions. It’s a convenient explanation — and sometimes a true one. But it’s also incomplete.

In reality, much of the technical debt organizations struggle with doesn’t start in code at all. It begins much earlier, during onboarding. It grows out of unclear decisions, missing ownership, and assumptions that were never made explicit. By the time it surfaces as something we label “technical debt”, the real cause is often far older and much harder to undo.

Where technical debt really starts

Most onboarding efforts are built around a clear and understandable goal: getting systems live. Environments are deployed, integrations are connected, users can log in, and go‑live is achieved. From a traditional project perspective, this looks like success.

But beneath the surface, another set of questions often remains unanswered:
Who actually owns the system once the project team steps away?
What behaviour is considered normal operation, and what counts as an exception?
Which decisions were consciously made as temporary measures, and which were intended to last?
What assumptions did the team rely on to move quickly?

When those questions are left unresolved, onboarding doesn’t just introduce new systems it also introduces uncertainty. That uncertainty isn’t visible on day one. It doesn’t necessarily cause incidents immediately. Instead, it lingers quietly, only surfacing later during change, scale, incidents, or handovers between teams.

The patterns that quietly create debt

Across many onboarding efforts, the same patterns tend to repeat. Not because of bad intent, but because of speed, pressure, and good people doing their best with limited time.

Often, long‑term ownership is never truly clarified. Responsibility exists during delivery, but accountability after onboarding remains vague. When issues arise months or years later, teams spend time debating who should act instead of focusing on how to solve the problem.

In other cases, decisions are explicitly framed as temporary — “for now”. Shortcuts, exceptions, or interim solutions are introduced to keep momentum going. But without a clear point where those decisions are meant to be revisited, “temporary” quietly becomes permanent.

Assumptions play a particularly powerful role. Capacity expectations, usage patterns, support models, and integration dependencies are often treated as shared understanding rather than documented facts. When assumptions aren’t written down, they don’t stay flexible, but slowly harden into reality.

Under time pressure, workarounds are another common pattern. What starts as a practical fix in the moment often ends up shaping how a system is operated for years. Over time, those workarounds define the norm, even though no one ever intended them to.

And finally, many onboarding processes focus intensely on go‑live, while what happens next is left implicit. Tuning, stabilization, and the transfer of ownership are assumed rather than planned.

None of this is poor engineering. It’s a natural result of moving fast without making alignment explicit.

How this debt shows up later

By the time someone calls the situation “technical debt”, the symptoms tend to feel familiar. There’s uncertainty about who owns changes. Parts of the system become “danger zones” that no one wants to touch. Manual processes exist that no one fully understands end‑to‑end. Improvements are postponed because the consequences are unclear.

Conversations start with phrases like “We’ve always done it this way”. 

At that stage, the debt feels deeply technical. But paying it down requires far more than refactoring code or upgrading platforms. 

Reducing technical debt starts before code

Many organizations try to tackle technical debt late, through cleanup initiatives or dedicated refactoring projects. Those efforts can help — but they rarely prevent the same issues from reappearing. 

The more effective place to intervene is earlier, during onboarding. That doesn’t require new tools or complex frameworks. It usually means doing a few simple things deliberately.

Øyvind Bredland - Team Lead Customer Onboarding, Cegal

Ownership needs to be made explicit from the start. Key decisions should be documented, along with the context and trade‑offs behind them. Assumptions should be written down instead of carried implicitly. Temporary decisions should come with a clear understanding of when, and how, they will be revisited. And onboarding should be treated as the start of operations, not the end of delivery.

At its core, this is about clarity.

Clarity ages better than shortcuts

Technology will change. Context will shift. Requirements will evolve. What enables teams to adapt isn’t the absence of debt, but the presence of clarity — clarity about why things were done, who owns them, and which assumptions still hold.

Most technical debt isn’t actually technical. It’s the result of uncertainty introduced early and never resolved. Reducing it rarely starts with code. It starts with being explicit, early, and willing to revisit decisions before they harden.

Onboarding doesn’t just introduce systems. It establishes expectations, habits, and boundaries that last long after delivery.

When ownership, decisions, and assumptions are left implicit at that stage, they don’t disappear. They resurface later as friction, uncertainty, and something we end up calling technical debt.

The earlier those things are made explicit, the easier everything becomes afterwards.