How do we prevent debates over whether changes to user stories are new work or bugs?

Question

I'm struggling to determine where capturing of user story elaborations and discussions fits into agile. A lot of what I have read and agree with is:

1. You should be focusing on discussions with your BAs and clients to elaborate the stories.
2. Figure out what needs to be done rather than documenting every single requirement.

How do we capture enough details so that in a month or so, when someone in those discussions comes back and their memory of it was different from ours, we don't get into a debate/discussion over whether it is a new story or a bug because we didn't implement right in the first place?

This debate occurs because of maybe the scale of the change required due to this disagreement. Do we need to capture every decision "on paper" to avoid debates? Doing this is appears a bit contrary to some of the Agile Manifesto.

Answer 1

How do we capture enough details so that in a month or so, when someone in those discussions comes back and their memory of it was different from ours, we don't get into a debate/discussion over whether it is a new story or a bug because we didn't implement right in the first place?

You and the customer are currently trapped in waterfall thinking. You're doing your planning upfront, and arguing over specifications later as if the project has one (and only one) bite at the apple for each feature. This is a misunderstanding of several foundational agile principles:

1. The need for ongoing collaboration.

   You can't capture a story or specification during upfront planning, when the cone of uncertainty is largest, and expect the story or its implementation not to change over time. User stories are conversation placeholders, not detailed specifications, so they're meant to be elaborated on in the iteration in which they are addressed. This is done by integrating the customer (or a proxy, such as a Scrum Product Owner) into the iteration through active collaboration.

2. Iterative development requires frequent course corrections.

   In iterative development, all parties need to embrace change as an integral part of the process. This is why iterative development requires a tight feedback loop, and prioritizes working features over "perfect" features. Iterations should be just long enough to complete useful increments, and the development team and customer should be inspecting the increment at the end of each iteration to refine it.

3. Iterative development is a continuous process.

   In agile frameworks, imperfections are not bugs or defects; they are simply additional work that needs to be done in a future iteration to incrementally improve towards the desired state. As you increase effective collaboration and communication, the number of misfeatures delivered will go down.

If you're only collaborating with your customer at the beginning of a project, or only gathering their feedback weeks or months after a feature has been considered a final deliverable by the team, then the blame-game that you're experiencing is inevitable. To avoid mutual finger-pointing, adapt your process to work more closely together. When you provide a customer with more transparency into the process, and more inflection points to inspect and adapt the product, you will change the dynamic from "us vs. them" to one of shared responsibility for the product.

Answer 2

Agile Manifesto says:

Working software over comprehensive documentation

but also!

That is, while there is value in the items on the right, we value the items on the left more.

So the answer is: as much documentation as necessary, but not more. Definitely do not make a habit for it. Try to avoid to have specification for each requirement just because you usually do it.

The description of user story has to be as good as allow you to work with it. As Barnaby Golder wrote. The requirements in the low part of the backlog do not have to be described in the high detail if the current description gives PO (Product Backlog) enough information to prioritize it.

The items which will be take in the next sprint or the following one are usually in more detail so that team can estimate them better or pull them to the sprint.

Maintaining extensive documentation is really a waste of time in Agile environment as customers can change its mind. (Last week our customer just changed his and decided that he does not need 3 features anymore. Boom. All time we spent on documentation and discussion became waste of time. We learned our lesson, until the feature is higher in the backlog, development team should minimize time spent)

So to wrap it up:

• first you need enough text per user story to allow PO to prioritize backlog
• later enough so that Development team can (roughly) estimate it
• at last enough so that Development team can develop it

So just ask the people, do you need more information? If not, do not waste time.

Answer 3

I will answer your question from the point of view of Scrum.

User stories may be captured weeks or even months before the sprint in which the work is done. But a user story is a simple one or two sentence description of the requirement. There will be few if any requirement details captured and nothing about the implementation. Because these stories are so simple they tend to have a long shelf life.

In Scrum we use a just-in-time approach to user story discussions. At the beginning of each sprint the team meets with the Product Owner during sprint planning. They run through each story they plan to include in the sprint and the Product Owner provides the details they need to do the implementation.

So it is only at the last minute that the discussion takes place and all the details are fresh in the team's minds as they start their work.

Also, the Scrum concept of the Product Owner is that they are the primary source of all requirements. The Product Owner spends a lot of their time speaking with stakeholders and builds up a strong understanding of what work needs to be done.

The Product Owner is also available to the development team throughout the sprint. If there are any questions or clarifications needed then the Product Owner is on hand to answer them.

Finally, at the end of the sprint the completed stories are demonstrated at the sprint review. This is an opportunity for the Product Owner and stakeholders to double-check that the new features are as they would expect them to be. If they spot a problem then any necessary fixes are added to the product backlog.

Answer 4

Document as much detail as you need to get the work done, which should normally include sufficient documentation for future support but not necessarily to complete further stories or defect fixes.

I believe the best answer to your question is simply to stop discussing whether something is a fix or a change. That should have no bearing on the amount of effort involved or the way you run the backlog. When considering a backlog item, what really matters is whether it is "ready" to start, whether it is useful to stakeholders and what priority it should have. If it helps to label things as a "defect" then great, but if it is wasting your time then just put everything in as a new item and leave it at that. I suggest you don't need a different process for handling defects versus handling new features.

Answer 5

I think scrum and agile in general dodge this question by always keeping the requirement very simple.

If you can't write the acceptance criteria down in a concise 'given x then y' style then you are doing too much upfront planning of the details.