On this page
The scariest artifact in freelancing is a requirements PDF. It arrives dense, confident, and written in the client’s language rather than the system’s — and somewhere between its bullet points and your codebase lives the number you’re about to promise: weeks, and money.
A device-protection client recently sent me exactly that: a document describing a major rework of how their platform charges customers. The old model was payment credits. The new one: a monthly coverage fee plus per-claim charges — a different business, financially, wearing the same product. My job was to answer the only questions that matter at that moment: how big is this really, how long, and how much?
Here’s how I scoped it, and where the AI did the work versus where it can’t.
Step one: make the document argue with the codebase
The traditional approach is to read the PDF, walk the code from memory, and produce an estimate that is mostly vibes with a spreadsheet on top. Instead, I gave the requirements document to an agent that also had the codebase, with a specific instruction: don’t summarize the PDF — map it. For every requirement, find what the system currently does, and name the delta.
That framing matters. A summary tells you what the client wants, which you already knew. A mapping tells you what has to change, which is what you’re actually pricing. The output was a feature-by-feature decomposition:
- The billing model itself — replacing the payment-credit flow with the monthly-fee-plus-claim-charges model, and everything downstream that assumed credits existed.
- A claim workflow with 14 distinct states — what the PDF described as a process paragraph decomposed, against the code, into a real state machine: which transitions exist, which need human approval, which states the current system had no concept of.
- Contract versioning with pricing snapshots — the requirement hiding the most work. If pricing changes over time, every existing contract must keep the terms it was sold under, which means contracts stop being rows you update and become versioned records with the price captured at signing. That’s a data-model change with tentacles.
- A typed payment ledger — replacing ad-hoc payment records with a ledger where every entry has an explicit type, so money movements are auditable and the new fee/charge split is reportable.
- Plus the supporting cast the client barely mentioned but the mapping surfaced — like admin-configurable email templates for the new lifecycle events.
None of these items was invisible before. But the decomposition forced all of them into the open at once, before quoting — which is exactly when you need them, because the expensive surprises in a rework are always requirements that looked like sentences and turned out to be subsystems.
Step two: the estimate comes out of the delta
With the mapping done, estimation stops being one big guess and becomes many small ones: breadth of change (which modules are touched), depth (schema change vs. logic change vs. new subsystem), and risk (does anything migrate live data — here, yes: existing contracts and balances had to survive the model change).
From that, a time and budget estimate — assembled per-item, then sanity-checked as a whole. Small guesses still carry error, but their errors are inspectable and they don’t all point the same optimistic direction, which is the classic failure of the single gut number. And when the client asks why the quote is what it is, the answer isn’t “experience” — it’s the mapping itself: here are the fourteen states, here’s what contract versioning means for your data, here’s the migration. The estimate becomes an argument instead of a posture.
What the human still owns
Being honest about the division of labor, because this is where AI-assisted scoping goes wrong if you let it:
Validating the mapping. The agent’s decomposition is a draft by a very fast reader, not a verdict. I walked the claims against the codebase myself — does this module really work the way the mapping says, is this delta really that shallow. Most claims held. The ones that didn’t were exactly the kind that would have blown the schedule.
The questions the PDF doesn’t answer. A requirements document is what the client wrote down, not everything they’ve decided — and some of what it implies, they haven’t decided at all. What happens to a claim mid-flight when its contract’s pricing version changes? Are the fees prorated? The decomposition is what surfaces these questions crisply enough to send back as a short, pointed list. Sending that list before the quote is itself a signal of competence that a bid number alone never carries.
The commercial call. What to bid, what to phase, what to decline, where the risk premium sits — that’s judgment about the client, the relationship, and my own capacity. No mapping produces it.
Why this is now my default
Scoping used to be the worst-leveraged work I did: unpaid, high-stakes, and rushed, because a proposal has a clock on it. The mapping technique changes the economics — the mechanical reading (cross-referencing a dense document against a real system) compresses from days to hours, and the human hours move to validation and the open questions, where they actually change the outcome.
The failure mode it prevents is the industry’s oldest one: quoting the document you were sent instead of the system you’ll be changing. The PDF describes a destination. The price lives in the distance — and the only way to know the distance is to make the document and the codebase confront each other before you name a number.