Scoping a Custom Software Project With an Agency: The Five Discovery Artifacts We Hand Over Before a Contract Is Signed

What Discovery Should Produce Before You Sign Anything

Pre-contract discovery should produce five written artifacts: an entity and event model, an integration inventory, a must-ship-first feature list, an explicit non-goals list, and an assumptions register. If an agency gives you only a price and a feature bullet list, the scope has not been bounded, it has been guessed.

The distinction matters because a proposal is a commercial document and these five are engineering documents. A proposal says "customer portal, admin panel, mobile app, 14 weeks." The artifacts say which entities exist, which of your current systems must be talked to and how, what ships in the first release, what explicitly does not, and which unverified beliefs the estimate is resting on. When something changes later, the artifacts are what you diff against. A bullet list gives you nothing to diff.

Discovery for a mid-sized build usually takes us one to three weeks and is paid, separately from the delivery contract. That is deliberate. Paid discovery means the output belongs to the client whether or not they hire us to build it, and it means we can afford to actually read their spreadsheets and call their lab's software vendor rather than guessing to keep a free pitch cheap.

• • Entity and event model: the nouns and the things that happen to them
• • Integration inventory: every external system, its real interface, and who owns it
• • Must-ship-first list: the smallest thing that is genuinely usable in production
• • Non-goals list: what we are explicitly not building in this contract
• • Assumptions register: every belief the estimate depends on, with an owner and a due date

The Entity and Event Model: Nouns First, Screens Later

The entity and event model is a one-page sketch of the core objects in the system and the state changes they go through. It is drawn before any screen is designed, because screens are cheap to redraw and data models are not. Getting the nouns wrong is the single most expensive scoping mistake available.

For a diagnostics platform the entities are things like customer, kit, sample, test run, result, and clinician review, and the events are kit shipped, sample received, run started, result released. For a farm-to-table marketplace they are retailer, product, order, batch, route, driver, and the events are order placed, batch closed, route assigned, delivery confirmed. Writing these down surfaces disagreements fast. On more than one engagement, two people from the same client gave different answers to "what is an order" within the first hour, one meaning a shopper's basket and the other meaning the per-retailer split that the warehouse actually picks.

We also mark, on the same page, which entities have history requirements. An entity that must be auditable forever is a different build from one that can be overwritten in place. Sample chain-of-custody, consent records, and payment state all fall into the first category, and if that is discovered after the schema is written, the rework is not a small patch.

The Integration Inventory: Assume Nothing Is an API Until Someone Shows You a Response

The integration inventory lists every external system the new software must exchange data with, and for each one records the actual interface, the data direction, the owner's name, and whether we have seen a real response payload. "They have an API" is not an entry. A sample response with a date on it is an entry.

This is the artifact that has saved us the most money, because it was born from losing some. On a lab systems engagement we scoped a handoff to laboratory instrumentation software on the client's assurance that an API existed. It did exist, in the sense that a vendor brochure said so, but the deployed version exported CSV files to a network folder on a schedule, with column ordering that varied by instrument. What we had priced as an integration became a file watcher, a parser, a per-instrument mapping layer, and a reconciliation report for rows that failed to match a known sample. None of that was in the estimate.

So the inventory now has one column that overrides everything else: evidence. Either someone on our side has hit the endpoint and pasted the response into the document, or the row is flagged as unverified and moves straight into the assumptions register with a date by which it must be verified. Third-party systems owned by someone who is not in the room, a payment provider, a lab vendor, a shipping carrier, a legacy ERP, are the rows most likely to be wrong.

• • System name and who inside the client organisation owns the relationship
• • Real interface: REST, SFTP drop, CSV export, webhook, database view, manual re-key
• • Direction and frequency of data flow
• • Auth mechanism and who can issue credentials
• • Evidence: verified with a live call, or unverified and logged as an assumption
• • Failure behaviour: what the product does when this system is down

Must-Ship-First and the Non-Goals List: Bounding Scope by Subtraction

The must-ship-first list defines the smallest version that can carry real production traffic, and the non-goals list names, in writing, the features that are explicitly excluded from this contract. The second document is the one clients underestimate. Scope is bounded far more reliably by what you write down as excluded than by what you write down as included.

A non-goal is not a rejection, it is a deferral with a paper trail. Typical entries from our engagements: no multi-language content in release one, no in-app payments on iOS, no self-serve retailer onboarding, no BI dashboard beyond three fixed reports, no offline mode for the driver app. Each one is something a reasonable person could assume was included. Writing it down converts a future argument into a future change order, which is a much better conversation to have.

The ordering rule we apply to the must-ship-first list is that a feature qualifies only if the business genuinely cannot operate without it on day one. Everything else, including things everyone agrees are important, goes into a second column. When a fitness community platform moved off spreadsheets, member booking and class scheduling had to exist on launch day. Social feeds, badges, and partner discounts were genuinely wanted and genuinely deferred, and the app shipped because of that split, not despite it.

The Assumptions Register: The Document That Drives Change Orders

The assumptions register lists every belief the estimate depends on, each with an owner, a verification date, and a stated impact if it turns out to be false. It is attached to the contract as an appendix, and it is the mechanism that makes change orders a calm administrative step rather than a relationship problem.

A well-formed entry reads like this: "Assumption: the retailer stock feed is available as JSON over HTTPS with hourly refresh. Owner: client ops lead. Verify by: week 1. If false: add 2 to 3 weeks for a file ingestion and mapping layer." Now nobody is surprised. If the assumption fails, the impact was priced before anyone had emotional investment in the number, and the conversation is about which of two known options to take, not about whose fault it is.

Pricing the failure case up front is the part that most scoping guides skip. An assumption without a stated consequence is just an optimistic note. We also keep a small register of client-side dependencies with the same structure: content, brand assets, test accounts on third-party systems, legal sign-off on consent copy. Those slip at least as often as technical assumptions do, and when they do, the schedule moves for reasons that have nothing to do with engineering throughput.

Four Scope Traps That Cost Us Money, and the Question That Catches Each One

Four traps have hurt us repeatedly: an assumed API that was a file drop, an unbudgeted App Store review cycle, business rules hidden inside spreadsheet formulas, and multi-sided marketplace roles that multiplied the screen count. Each one now has a specific discovery question attached to it.

The App Store trap is the most avoidable and the most commonly ignored. A mobile launch date is not a build completion date. Review can reject a build for reasons that have nothing to do with code quality, including account deletion requirements, sign-in options, permission strings, and how a subscription is presented. We now budget review cycles as calendar time in the plan and get a build through review early with a skeleton feature set, so the first submission is not also the launch submission.

The spreadsheet trap is subtler. When a business runs on spreadsheets, the real business rules live in nested formulas, conditional formatting, and in what one person does manually every Friday. Nobody describes those in a requirements workshop because nobody experiences them as rules. We now ask for the actual files during discovery and audit the formulas, because a single pricing sheet can encode discount tiers, rounding behaviour, and seasonal exceptions that no stakeholder will mention out loud. The marketplace trap is the arithmetic one: every additional participant role multiplies not just screens but permission rules, notification paths, and state transitions, so an organiser, a guide, a company, a consumer, and an admin is not five times one role, it is five roles plus the interactions between them.

• • Assumed API: "Can you send me a real response payload from the live system this week?"
• • App Store review: "What is the latest date a rejected first submission can still hit our launch?"
• • Spreadsheet rules: "Can we have the actual files, including the ones with the macros nobody maintains?"
• • Marketplace roles: "List every role that can log in, and for each, the one screen they cannot do their job without."

For what happens after scoping is agreed, including contracts, team setup, code ownership, and handover, see the Jaspero Client Handbook.