Discovery, documentation, and acceptance criteria: when a simple mapping stops being simple
Over the past few months, I have been working on a product that looked simple to explain at first.
In theory, it was almost just a mapping exercise.
You receive information on one side, understand how it should be represented on the other, and build the bridge between the two.
It sounds like the kind of project you can sketch in a meeting, break into a few tasks, and start building.
In practice, it turned out to be the exact opposite.
The further we moved, the more exceptions, dependencies, conflicting interpretations, and scenarios started showing up — things nobody had put on the table at the beginning.
And that made one thing very clear to me:
what saved the project was not getting everything right on the first try. It was having a methodology good enough to quickly expose when we were wrong.
The problem is almost never the mapping itself
When someone describes a product as a simple mapping exercise, they are usually looking at the happy path.
Field A becomes field B.
Status X becomes status Y.
Rule 1 produces result 2.
But real products rarely live only on the happy path.
Then the questions start:
- what if this field is empty?
- what if two systems treat the same status differently?
- which system is the source of truth?
- what happens to historical data?
- is there a business exception?
- can the user correct it?
- do we need to keep history?
- does the behavior stay the same for every profile?
- what happens if an integration fails halfway through?
None of these questions changes the original idea of the product.
But each one can completely change the implementation.
That is when I started realizing that good discovery is not only about figuring out what to build.
It is mostly about discovering where different interpretations exist before they turn into code.
Discovery is not one meeting before development
I used to think about discovery as a fairly well-defined phase.
You talk to the right people, understand the problem, document it, close the scope, and move into delivery.
Today I see it a little differently.
In products that depend on business rules, integrations, and several stakeholders, discovery keeps happening during development.
The first discovery creates a model of the problem.
Development starts testing that model against reality.
And inevitably, situations appear that were never predicted.
The difference between a healthy project and a chaotic one is what happens next.
A question appears.
That question becomes an objective conversation.
The conversation becomes a decision.
The decision becomes documentation.
And the documentation becomes expected behavior.
That cycle sounds bureaucratic when written down like this.
In practice, it prevents a huge amount of rework.
Good documentation is not big documentation
Another thing this project reinforced for me is that more documentation does not mean better documentation.
You can have a massive page describing a product and still leave a developer unsure about what should happen in a specific scenario.
To me, documentation starts becoming truly useful when it can answer three things:
what happens, why it happens, and how we know it happened correctly.
The first explains the behavior.
The second preserves the context behind the decision.
The third starts taking us toward one of the most important parts of the process: acceptance criteria.
Acceptance criteria are where abstraction ends
"We need to sync this data."
"This status should appear on the new screen."
"The system needs to perform the mapping."
All of that may be correct and still be insufficient to build anything.
Acceptance criteria force the conversation to move from intent to observable behavior.
If the data does not exist, what appears?
If the integration is down, does the user see an error or do we retry?
If two pieces of information conflict, which one wins?
After saving, how long should it take for the other system to reflect the change?
Who is allowed to perform the action?
What must never happen?
To me, one of the biggest values of writing good acceptance criteria is simple:
they expose ambiguity.
Sometimes you start writing a criterion thinking the rule is fully understood, and halfway through the sentence you realize there is still a hidden product decision.
It is much better to discover that while writing a task than after someone has already implemented half of the solution.
Acceptance criteria also improve the conversation
One interesting thing is that acceptance criteria do not only help the people building the product.
They improve conversations with stakeholders too.
It is much easier to validate:
"If X happens, the system does Y. If Z happens, we do W. Is that correct?"
than to ask:
"Is the flow correct?"
The second question almost always gets a "yes."
The first forces everyone to look at the same scenario.
That reduces the classic situation where product, business, and engineering leave the same meeting believing they agreed — while each person understood a different solution.
Being assertive does not mean having every answer
This project also helped me separate two things that look similar: confidence and certainty.
As a Product Owner, I do not need to enter every conversation already knowing every rule.
But I do need to know which uncertainty I am trying to resolve.
There is a huge difference between getting five people together and saying:
"We need to understand this flow better."
and saying:
"We currently have three possible interpretations for this scenario. Implementation is blocked because we do not know which system is the source of truth. We need to leave this meeting with that decision."
The second conversation is usually much shorter.
And much more useful.
That assertiveness does not come from knowing everything.
It comes from doing the work before the meeting: understanding the gap, gathering evidence, drawing the scenarios, and turning a broad discussion into a specific decision.
The team does discovery too
Another important lesson was to stop treating discovery as something owned exclusively by product.
A developer finds a hidden rule.
QA finds a scenario nobody considered.
A stakeholder notices an exception once they see the behavior working.
Someone from the business remembers a manual process happening outside the system.
All of that is discovery.
If the team feels comfortable raising those questions early, the product gets better.
If the environment treats every new understanding as "scope change" or planning failure, people start hiding doubts and simply implement the interpretation that seems most likely.
Then the problem only appears later — and at a higher cost.
Documentation becomes project memory
As more decisions started appearing, documentation gained another important role: preventing the team from having the same discussion again and again.
A decision made only in a meeting disappears quickly.
A few weeks later someone asks:
"Why did we do it this way?"
And the conversation starts all over again.
When the decision is recorded together with its context and acceptance criteria, it becomes part of the product's memory.
That does not mean the decision can never change.
It means that if it changes, we know what is changing and why.
That difference looks small, but in long-running projects it is huge.
The best process does not eliminate surprises
Even doing all of this, we still keep finding challenges along the way.
And I think that is the most important part.
Good discovery does not promise that no surprises will ever appear.
Good documentation does not predict every future edge case.
Acceptance criteria do not make requirements immutable.
What these tools do is make the team better prepared to absorb surprises without losing control of the product.
When a new rule appears, we can understand where it impacts.
When a stakeholder brings an exception, we can compare it with the behavior that had been agreed on.
When a developer finds an inconsistency, there is a clear place to turn it into a decision.
In this case, methodology did not make the work more bureaucratic.
It kept everyone looking at the same version of reality.
What I now consider a good product handoff
Today, before I consider a demand truly ready for development, I try to make sure at least four things are true:
- The problem is understood. Not only the requested solution.
- The main flows and most relevant exceptions are explicit.
- Important decisions have their context recorded.
- The acceptance criteria let anyone on the team objectively say whether the behavior is working or not.
We do not always get to 100%.
In fact, we probably never do.
But the difference between starting with 40% understanding and starting with 80% becomes visible very quickly during delivery.
In the end, the job is to create shared understanding
I started this project thinking most of the challenge would be organizing a mapping between systems.
Today I think that was the easy part.
The hard part is getting people with different contexts — product, engineering, business, and stakeholders — to build the same mental model of what the system needs to do.
Discovery helps build that model.
Documentation keeps it from disappearing.
Acceptance criteria turn it into something verifiable.
And assertive conversations correct the path whenever reality shows that our model was incomplete.
Maybe that is one of the biggest things I have been learning while working with product:
often, the most important deliverable from a Product Owner before the software exists is not a specification. It is alignment.
The code comes after that.