Testing a spec before writing a line of code
A client arrived with a spec already priced by another developer. Before answering, I treated it like code: I tested it. Dozens of unanswered questions later, the real conversation could start.
A spec never arrives on its own
The client arrived with a document already written, already priced, and a budget already fixed. In plain terms: another developer had done the groundwork, and I was there to execute at that price. It is a common situation in freelance work, and not disqualifying in itself. What matters is what is in the document.
Before saying no, I tried four things to keep the project. Here they are, in order.
Attempt 1: test the spec
I did to that spec what I do to code: shift-left testing. Not proofreading: actively hunting for what will break. What happens if the user drops out halfway through the journey? Who is allowed to change what? What do you see when the list is empty? What is the expected behaviour when a payment fails?
The result: dozens of questions with no clear answer, and a fair number with no answer at all. That is not a criticism of the document. It is simply what happens to any specification nobody has attacked yet.
Testing a spec before you code costs ten times less than fixing it afterwards.
Attempt 2: rewrite the spec, and bill for it
I offer to redo the spec from scratch, at his expense, so we start from a base we both read the same way. He declines. That is his call. But a vague spec is a guarantee that the project will drift. And drift always gets paid for: just later, and at a higher price.
Attempt 3: ship in prioritised batches
Since we could not clear everything up in advance, I offer to work in iterations, with MoSCoW prioritisation: what must be delivered, what should be, what could be, what will not be. Shipping in small batches cuts the risk on both sides: he sees progress, and I am not building for six weeks in the dark.
He agrees. At that point I think, right, we're going to get there.
Attempt 4: tie payment to deliverables
That is where it stopped. When I say payment will follow the iterations, he refuses. He wanted three instalments pinned to the calendar, the largest one in the middle. In other words: if the project stops midway, I have worked for nothing. Payment has to follow deliverables, not dates. It is the only way to line up both sides' interests.
The last straw
One final request: start with no deposit, "to see how it goes over two weeks". So not even enough to secure the very first iteration. The argument put forward: "with AI, everything is easy and fast these days".
What AI does not do
AI speeds up the code. It does not replace scoping, or trust, or respect for the work. An ambiguous spec produces exactly the same failed project it always did, just faster.
Turning down a project is not losing a client. It is protecting your time, your energy, and the quality of what you deliver elsewhere.
Bonus: the questions I ask a spec
This is my shift-left testing checklist for specs. It does not cover everything, but if a document answers none of these questions, you already know how the project is going to go.
The journeys
- What happens if the user drops out halfway through a journey (sign-up, order, payment)? Do they resume where they left off?
- What do you see when there is nothing to show: empty list, no search results, blank history?
- What is the expected behaviour on failure: payment declined, file too large, connection lost mid-upload?
The permissions
- Who is allowed to create, edit and delete what? And who can see what?
- What happens to the content of a deleted or deactivated user?
The data
- Which fields are required, which are optional, and what do you show when an optional one is missing?
- Are there limits: text length, file size, number of items? What happens when you hit them?
The scope
- For each feature: is it essential at launch, or can it wait for a later iteration?
- What is explicitly out of scope? (The question that prevents the most end-of-project arguments.)
- How will we know the project is finished? What is the acceptance criterion for each deliverable?
A spec that answers all ten of these on the first pass almost never exists. That is fine: it is exactly what the scoping phase is for. The problem is coding without having asked the questions.