Technote

Development workflow Advanced

Series What to know before you hire a developer Part 8 of 8

Spotting the signals of technical debt without being a developer

You can see debt without reading a line of code. The signals appear first in schedules, conversations and screens.

Technical debt is borrowing against later in order to move faster now. That is a reasonable trade under pressure, and every project carries some. The trouble starts when the borrowing continues and nothing is ever repaid — and you can notice that state without reading code, because the signals reach schedules and conversations before they reach anything technical.

This is the final part of the series: a list a founder can run through roughly once a month.

Signals in the schedule

The easiest signal to spot is that similar-sized jobs keep taking longer. Adding a page used to take a day and now takes three; changing a single sentence now requires review. Nobody has become lazy — the structure has reached the point where touching one thing means checking several others.

A concept diagram illustrating how effort grows for identical work — not measured data

The second signal is how often a fix breaks something else. Repeated reports of “we changed A and B stopped working” mean the site has become fragile under change. The remedy is not to press the people harder; it is a test environment and a checking procedure.

Signals in the conversation

Some signals show up in language. Be alert when “don’t touch that part” becomes a recurring phrase. If someone can explain why, that is fine — but a prohibition nobody can justify, kept alive as custom, is the classic shape of debt. Usually it means whoever built that part has already moved on.

“We’re not updating because it might break” belongs to the same family. The statement is honest and may well be true. But it should describe a temporary state, and it should arrive with a plan for when and how it gets resolved. Without one, the update gap widens with every month until it becomes a single step nobody wants to take.

What you can check on screen

Several items are visible from the admin screens to anyone, technical or not. Five minutes a month is enough.

A five-minute monthly check — every line is verifiable without reading code

The unmaintained plugin line is the important one. Anything whose last update is far in the past sits in a state where a discovered problem will not be fixed. That calls for a decision — find a replacement or drop the feature — and postponing that decision is itself the debt.

Repaying it — not all at once

Seeing debt and deciding on a full rebuild is usually an overcorrection. A rebuild disturbs the search standing, the content and the working habits you have accumulated along with the code. Paying it down in order is almost always the better move.

The order for repaying debt — diagnosis comes first and a rebuild is the last option

Start with a diagnosis: a written list of what is in what state right now. Then sort by risk — anything touching security first, anything merely inconvenient later. Then work through it one item at a time, recording before and after for each. The record is what stops you making the same judgement twice.

Closing the series

Across eight parts we have gone from writing requirements to reading quotes, sorting out ownership, agreeing acceptance criteria, taking handover, drafting a maintenance agreement, choosing a partner, and finally reading the signals of debt. One principle runs through all of it: write down what you agreed out loud, and most problems disappear. You do not need technical knowledge to apply it — and the technical side works to the same principle.

This checklist points at us as much as anyone. What we do and explicitly do not do is set out as scope and exclusions on the optimization program page, and the order we work in and the records we leave are published on our process page. If you would rather look at your own site first, the diagnostic on the free tools page is a reasonable place to start.

More on this topic

All technotes

Development workflow Practical

Turning taste arguments into rule checks

"It feels a bit cramped" can be neither argued with nor fixed. Spacing off the scale, colour off the palette, contrast below threshold, missing states — four rules…

Designers 9 min read

Development workflow Practical

Do not swap everything at once

A full swap makes every problem appear at the same moment — which means none of them can be attributed. So you switch one template at a time.

Designers 6 min read

Development workflow Practical

Adding an SCSS build, and whether to commit the output

WordPress themes are expected to deploy without a build step, which leads to the opposite conclusion from ordinary application code — and to its own costs.

Developers 7 min read

₩270,000 · Join the program