From Unclear Specs to Production in 2 Weeks

Every project that lands on my desk starts the same way: the client knows the problem hurts, has a rough picture of the solution, and cannot write down precisely what it should do. That is not a failure on their side — it is the normal state of real work. Ambiguity is normal. The trick is to turn it into a sequence of small, testable decisions instead of waiting for a perfect specification that never arrives.

Here is the framework I use to go from a fuzzy first call to software running in production within two weeks.

Start with the riskiest assumptions

Every unclear spec hides a handful of assumptions that can kill the project. I hunt them down before writing any product code. Three categories show up again and again: data availability (does the data we need exist, and is it clean enough to use?), integration limits (does the third-party API actually support the operations we are planning, at the volume we need?), and real user workflows (does the process we imagine match what people actually do all day?).

Rank the unknowns by how much damage they can do, not by how interesting they are. Then validate the deadly ones with the cheapest experiment possible: one curl request against the API, one query on a dump of production data, a fifteen-minute call with the person who will use the tool every day. A blocker found on day two costs you a conversation. Found on day twelve, it costs you the deadline.

Write for outcomes, not tasks

With the risks visible, I write the spec — and I keep it to one page. A one-page spec with success criteria beats a long task list, because task lists rot the moment reality moves, while an outcome stays true. The goal of the page is alignment on what “done” actually means, in words a developer and a stakeholder read the same way.

Mine always has the same four blocks: the goal in one sentence, measurable “done” criteria, hard constraints, and an explicit out-of-scope list. It reads like this:

Goal: warehouse staff confirm orders without touching Excel
Done means:
- an order moves from "new" to "confirmed" in under 30 seconds
- errors surface to the user, not to a log nobody reads
- works on the scanner tablets already in the warehouse
Out of scope: reporting, multi-language, bulk import

Everyone signs off on that page by day three. When a new idea shows up mid-project — and it always does — we hold it against the page: does it change what “done” means, or is it version two? Nine times out of ten, it is version two.

A two-week cadence

With risks tested and “done” defined, the build runs on a fixed rhythm. Fourteen days, four phases, no exceptions:

• Days 1–2: discovery, constraints, and a thin prototype. Confirm the risky assumptions, lock the constraints, and deploy a walking skeleton — one happy path, end to end, on a staging URL the client can click.
• Days 3–7: core implementation and automated tests. Build the features that make the outcome true, and nothing else. Every behavior in the success criteria gets a test, so “done” is verifiable, not debatable.
• Days 8–10: polish, edge cases, and QA. Handle the ugly inputs, the empty states, and the error paths. Walk through the app with a real user's data, not demo fixtures.
• Days 11–14: release, monitoring, and feedback loop. Ship gradually, watch the logs and metrics, and sit next to the users during their first sessions. The first day in production teaches more than a week of meetings.

The cadence works because it converts ambiguity into decisions on a schedule. Two weeks is short enough that nobody has time to drift, and long enough to ship something real. And the demo at the end is the best specification tool I know: clients who cannot describe what they want can always tell you exactly what is wrong with the thing in front of them.

• Attack the assumptions that can kill the project before writing product code.
• Define “done” on one page with measurable criteria; everything else is scope to negotiate.
• Ship on a fixed fourteen-day rhythm — the real specification is the feedback from production.