Let's consider a simple story for a user authentication screen:

As a user,
I want to be able to login with my username and password
so that I can do xyz.

This looks good, but all of the details related to what should happen when the password is incorrect, how many retries should be allowed, validations, and a bunch of other stuff that should go in with that story are missing.

Where should all that information go in an agile Scrum setup? Is it an FRS (or any other equivalent monolithic document containing details of all functional specs)? If yes, given there will be hundreds or thousands of these tiny stories, how should references to their corresponding FRS sections kept in sync with each other? How best to manage this level of detail in an agile Scrum world?

  • 1
    On a side note, having "hundreds or thousands of tiny stories" is generally an anti-pattern in itself. Most of what you're envisioning as stories are better captured in tests, the Definition of Done, or items on the Sprint Backlog (if they have to be captured at all). User story development is an art, not a science, so please browse the user-stories tag or read Mike Cohn's books on the subject for more thorough guidance on how to find the right balance of granularity for your project.
    – Todd A. Jacobs
    Apr 11, 2019 at 9:25

5 Answers 5


You've basically hit on the purpose of user stories. You see, user stories arose when we had large requirements documents that had all of the details the dev team could possibly need to develop the software. The problem with this is that those details take a long time to document and it turns out, they often aren't what the user wants (or at least miss the mark). Now all of that time has been wasted. Instead, we write a user story gives us just enough information to have a conversation with the person who wrote it. The dev team can ask questions and get a better understanding of their needs, then build something that meets them. They'll write their notes someplace and depending on your application, it might even make sense that those are stored in a very specific place. So, the purpose of user stories was to get away from monolithic documents and move to personal conversations. If you are tying a user story back to details in a large requirements document, you've eliminated the value of user stories.



The short answer is that you don't. Big, upfront planning is orthogonal to agile development. Instead, you should focus on iterative and incremental development with tight feedback loops to ensure that you're building the right things and embracing change throughout the project's life cycle.

Big, Upfront Requirements an Anti-Pattern

Doing detailed or large-scale requirements at the inception of a project is an agile anti-pattern. In particular, the Manifesto for Agile Software Development values:

Working software over comprehensive documentation[.]

Likewise, Scrum Theory explicitly avoids the use of fixed, upfront planning:

Scrum employs an iterative, incremental approach to optimize predictability and control risk.

While there is nothing stopping you from linking user stories or other types of Product Backlog Items to functional requirements, doing so is often a "project smell" that you're fixing scope, which is ideally the movable part of the Iron Triangle in Scrum. Furthermore, it's often an indication that you're making implementation decisions too early in the process. Lean practices require that you make architectural and design decisions at the last responsible moment, which is almost never at the very beginning of a project when functional requirement specifications are usually gathered.

What to do Instead

Within the Scrum framework, you should be leveraging the framework to perform just-in-time planning at the proper level of granularity. In particular:

  1. Leverage Backlog Refinement to identify work that will likely be in scope for the next iteration, maximizing the amount of work not done.
  2. Use Sprint Planning to decompose work into tasks and deliverables only for the current increment, optimizing for just-in-time planning.
  3. Leave implementation details out of Product Backlog and (most) Sprint Backlog items, allowing for greater flexibility.
  4. Gather feedback from stakeholders during the Sprint Review to identify changes and refinements to be treated as new work, allowing the project to continually evolve to meet changing market demands and to take advantage of lessons learned.

While not required by Scrum, agile practices generally require integrating test-driven design or behavior-driven development (often in collaboration with stakeholders or customers) to ensure that any functional requirements in scope for the current iteration are well-defined and testable. This type of "living documentation" is often more useful, more accurate, more maintainable, and more effective than typical functional requirements documents.

  • This appears to be only a partial answer. If you don't write a large requirements document, where (and when) do you take note of those pesky details like number of login attempts and required password strength. Those are not implementation details that you can completely leave out. Apr 11, 2019 at 5:52
  • @BartvanIngenSchenau "Pesky details" should be driven out empirically. Simple or obvious ones are generally captured in executable tests when a feature comes into scope. Others will be discovered through the inspect-and-adapt cycle, and become refinements captured as new work for future iterations. The whole point of many agile practices is to avoid over-constraining the solution space and encourage emergent design, which is why you should not spec out implementation details until the last responsible moment.
    – Todd A. Jacobs
    Apr 11, 2019 at 10:34

I think part of the problem is that this:

login with my username and password

is not a requirement. It's a design choice masquerading as a requirement. The real requirement is something like: "As a user I need to (securely and uniquely) authenticate with the system so that I can ..." Choosing username and password immediately rules out other, lower friction, means of authentication. Already logged in to Active Directory/G Suite/Office 365/another Oauth provider? Can we use that? What about facial recognition and fingerprint? Is that sufficient?

Keep this in mind as you go through your user stories. Are they telling you how something should be done instead of what needs to be done? Quite often this is OK; they're expanding on/clarifying earlier design choices. But sometimes it's worth taking a step back, asking yourself what problem are they really solving, and is there a better way?


As said by others, details should be clarified at the last responsible moment, sometimes at the moment of implementation in close collaboration between developers and e.g. business people or UX experts. However, specific information could be noted as acceptance criteria. More general and repeating criteria may be better placed within the team's (or organizations) Definition of 'Done'.

For acceptance criteria you may also want to take a look at a syntax like Gherkin -- and you may want to automate testing with things like Cucumber as a living, more value-adding documentation and base for regression testing.


"how many retries should be allowed, validations, and a bunch of other stuff that should go in with that story are missing. Where should all that information go in an agile Scrum setup?"

That is why you have acceptance criteria.

But it seams to me that you have another problem: who wrote your FRS? Why you did that investment, if you knew it will be agile project? In agile team decides technical details. If you read agile manifesto carefully, you will see that it is developers call for revolution.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.