The discovery document: why I write before I build
Most projects go wrong before a line of code is written. Here’s the deliverable I lead every engagement with — what goes in it, and why a client’s Head of Product called it a new quality benchmark.
A quote before understanding is a guess
Every failed project I have been near shares one ancestor: someone priced the work before anyone understood the system. The estimate then becomes the plan, the plan becomes the commitment, and eighteen months later a team is defending a number invented by a person who never read the codebase.
A paid discovery breaks that chain. It is small, it is fixed-scope, and it produces a document you own whether or not I build anything afterwards.
What actually goes in it
Four sections, in this order. Each one exists because leaving it out has cost someone money.
If a section cannot change what someone does on Monday, it does not go in the document.
- 01Current state, as it isThe architecture as it actually runs — not as the wiki claims. Drawn from the code, the deploy pipeline and two afternoons of questions.
- 02Decisions on the tableEach one with its options and the trade-off in plain language. No recommendation without the alternative it beat.
- 03Risks with an ownerA named person and a cost per month. A risk nobody owns is a sentence, not a risk.
- 04A sequence, not a GanttWhat has to be true before the next thing can start. Dates come later, from the team doing the work.
What it looks like in practice
Three engagements, three different shapes. The structure held; the emphasis moved to wherever the risk was.
Write for the person who signs it
The test I use: can a non-technical stakeholder read it end to end and correctly explain the recommendation back to me? If not, it is notes, not a deliverable. That constraint forces clarity that benefits engineers too — vague thinking cannot survive being written down for an audience that will not fill the gaps for you.
If a stakeholder cannot explain the recommendation back to me, it is not written well enough yet.
It also makes the document durable. Six months on, when the team has turned over and the context is gone, it is the only artefact that still explains why the system looks the way it does.
- One page a stakeholder can act on, before any appendix.
- Every claim traceable to something I saw, not something I was told.
- Options written so the client can disagree with me on the evidence.
The document is also the cheapest way to find out whether we work well together.
The discovery is the product. Everything after it is execution.