This answer will focus on how to work with User Stories and lower level requirements. I won’t be discussing the virtues, or lack thereof, of Scrum or Agile. I won’t be talking about gurus either.

This answer assumes you’re on board with Scrum but haven’t yet found a way to make it work for you.

As others have mentioned, User Stories are meant to cover how the Users would like the software to be. Because the Users don’t care about low level implementation stuff like database tables, constraints, architectural patterns, etc, you won’t find such details in a User Story.

However, that doesn’t mean these details should not be recorded anywhere.

When developers implement User Stories they need to be aware of lower level details typical Users won’t know. This information can come from SMEs, BAs, the Product Owner, your architect, or any other expert or technically minded person.

Does this mean low level details should be recorded in User Stories? No (and yes).

At some point between the time the story is created and implemented somebody will need to work out how to implement it. This usually takes the form of conversations with the people involved in the Story (User, architect, developer, etc). These conversations should result in unambiguous Acceptance Criteria which clearly delineate the scope of the User Story’s implementation. These details will need to be recorded somewhere and where that is is really up to you. The key here is that these details are elicited after the User Story has been created. I think this is what your guru is trying to emphasise.

As a developer it is clear that you’ll need a way to associate more specific requirements with your User Story. Just how you do that is entirely up to your team.

If people on your team want to keep these details out of the User Stories then you may need to respect that. There are benefits to keeping your high level User Stories free of implementation details. It keeps them lean and your backlog can be read as a history of what your Users and Product Owner wanted. Just make your needs as a developer known as well. You should be able to work out a compromise where simply linking to the User Story keeps everyone happy.

Yup, its BS. And Scrum is not Agile.

I hate the rigidity of so-called agile practitioners who tel you that there is one way of doing agile and that you must follow all the rules laid out in the holy scriptures of whichever ‘agile’ methodology they use. Its all BS.

Agile is about being agile.

Agile is about getting stuff done with a minimum of overhead. This doesn’t mean “no documentation” as you usually end up documenting more in an agile role, you just get on with the documenting without having to plan a process for doing the documentation. Similarly with coding, testing and requirements capture. The only things that matter in an agile process are those that help you get your job done, quickly and efficiently without any BS.

So in this case, if putting user requirements in the cards helps you write, test, document and demonstrate the code that is needed… put the requirements on the card and tell the gurus that the team is always right.

What does the rest of your dev team think? In a true agile methodology, if they all think requirements should be written up front without any ‘user conversations’ then that should be it, you do what the team thinks works best for them to do their work. If the team thinks that the user conversations are a good thing, then listen to them and understand why they think this and bring yourself into their way of working.

Just don’t call this a User Story and everyone will be happy.

I think the answer is, you can write this down wherever you want.

In general, specific implementations are not included in a user story for a few reasons:

1. You know what the customer wants, but you don’t know how it is going to be implemented.
2. The customer is aware there are more specific requirements involved, but really doesn’t care and/or understand them anyway.
3. Everyone thinks they are fully aware of the specific implementations at this time, but nobody wants to write them down because in their experience, it is all going to change anyway and no one will want to rewrite it.

There are no rules that omit additional documents when necessary. Maybe the client needs access to it and maybe not. If you’re hopes are to generate some sort of contract between you and the client on the specific implementation as if you can follow it and when it doesn’t work blame the client for agreeing to it, you’re mistaken. If the client understands the technical details of credit card processing, you should share these documents with them and possibly make it a part of the conversation.

I think if what your Scrum consultants are telling you is that Scrum doesn’t require requirements then you have some very poor consultants. They are even wrong to tell you that a user story is not in fact a requirement at all, they just happen to be one kind of requirement.

What are the different types of software requirements?

Business Requirements

These are generally a high level business need, something that generally would amount to some kind of executive style statement about a system. It is purposely high level and broad and by itself cannot be implemented without vastly more detail.

User Requirements

These are the User Story requirements that you are familiar with. They can generally fit on a sticky note.

• Actor – Typically a user or stakeholder.
• Need – Some item or general functionality that is needed by the user
• Reason – The reason or context behind why this need exists
• Acceptance Criteria – This is the framework for user acceptance testing and during Sprint Demo how the Product Owner will be able to decide if a user story is Accepted or not.

Functional or System Requirements

This seems to be the missing piece in your puzzle. Driven from the user level requirements, a functional requirement defines system level actors and properties of a system, as well as behaviors and functions of a system. This could also be done in a story format and included in your backlog. These items should stand alone and can be implemented independently of any one user requirement.

• Actor – A system or component of some kind.
• Need – A need, or property, or statement of behavior of a system that should exist.
• Reason – A context behind why this is needed in the system
• Acceptance Criteria – Scenarios, behaviors, functions and flows that are necessary to communicate how System and Integration testing should be performed. When these types of tests are passed for the requirement then we know this functional requirement has been completed. These can exist in external documentation from your user stories but should be completed prior to these stories being assigned in a sprint.

The functional requirements define your solution which sounds like what you are describing as the gap in your process.

Notable requirement types that need mentioned but are inconsequential to your question: Non-Functional Requirements, Technical Requirements, etc…

I think the purpose of this approach is not to constrain user stories, but to prevent bad requirements.

In my experience, users are generally incapable of writing requirements. Developers are generally incapable of writing requirements. Heck, let’s just admit it straight out: requirements are hard to write!

I think it would be valid for a user to write something in requirements lingo as part of a use story. However, doing so should not automatically make it a requirement. Having two conflicting use stories is a minor issue; having two conflicting requirements is a major contract-breaking issue. There’s no sense in promoting one to the other before its time.

I think the draconian viewpoint comes from a recognition of human nature. If people start thinking of user stories as a place to put requirements, they will begin to do so. The real advantage of use stories over other means of gathering requirement like information is that they are worded in user’s natural wordings and notation. This makes it more likely that the developers are thinking from the perspective of the customer. In a perfect world, cold requirements lingo could go there as well. In reality, such words tend to cause developers to latch onto the easy to understand requirements and miss the subtle wordings and nuances agile development wants to unearth using use stories.

TL;DR

User stories are for documenting what value should be added to the product, and why. Implementation details (e.g. how the value should be added, tested, measured, or validated) are constrained by the story, but are not contained within them. They are deliberately left as separate artifacts to maintain flexibility and agility within the framework.

The specifications and implementation details are most often captured in other artifacts such as Acceptance-Test Driven Development (ATDD), Test-Driven Development (TDD), and Behavior-Driven Development (BDD) scripts and scenarios. These particular artifacts aren’t mandated by the Scrum framework, but they will certainly give you a good starting point if you don’t already have other effective process controls in place.

User Stories Are Not Specifications

The original poster (OP) asked the following question:

[A] customer wants a different processing for different credit cards, there are strict requirements that must be implemented and known so that test cases can be written… WHERE SHOULD I PUT IT IF NOT IN THE STORY?

A user story is a feature that delivers value, provides some context to guide conversations about implementation, and a point of view tied to a value consumer who will benefit from the value delivered by the feature.

The whole point of a user story is that the implementation details are not prescriptive. The team is free to implement the feature in any way that delivers the identified value to the value consumer within the appropriate context.

A Worked Example

A Sample User Story

This is easier to explain if you start with a less ambiguous set of user stories. Since the OP didn’t provide an actionable user story that follows the INVEST mnemonic, I’ll invent one for the sake of an example. Consider the following story:

As a user who prefers to pay by Discover card,
I would like the option to make my purchases with the Discover card
so that I am not limited to Visa, Mastercard, or American Express.

This provides a concrete feature, provides some context that can guide the implementation decisions the team must make, and identifies the value consumer as a Discover-card owning customer. That’s not a set of specifications, but it’s what you need to have the right conversations with the customer and with the team about how best to implement the story during an iteration of development.

Analysis and Implementation

The actual implementation is up to the team. The team will have to do some analysis to determine:

• The easiest way to implement a new feature.
• Which of the various implementation options will be easiest to support going forward, without accruing technical debt.
• How to apply the open-closed and YAGNI principles to ensure that your new feature is robust without being over-engineered.

One of the core principles of the Agile Manifesto is customer collaboration. A cross-functional, self-organizing team is expected to be able to collaborate with the customer to work out the implementation details within the guidelines provided by the user story.

If your user stories are not written well, or if the team doesn’t have the skills or process maturity to do the just-enough analysis required by their agile framework, then this will obviously be much harder than it needs to be. Whole books have been written on the subject of how to create good user stories at the properly level of granularity; there is unfortunately no silver bullet, but it is a learnable skill for agile teams.

Test-Driven and Behavior-Driven Design

The best way to ensure that the analysis is sound, and that the implementation is both sane and supportable is through the use of TDD and BDD practices. For example, given the story above, the team should capture the planned implementation through artifacts such as:

• Cucumber features with testable scenarios.

  This is most useful for driving the development of acceptance tests, and for documenting user expectations of application behavior. For example, the user story should have one or more related Cucumber features that describes how the user is able to check out with a Discover card, and what that process looks like to the user.

• RSpec tests that validate the behavior (not the internal implementation details) of new code features.

  This is most useful for documenting and validating the intended behavior of the feature within the application. For example, the user story will drive the creation of unit and integration tests that ensure that using a Discover card invokes whatever card-specific behavior the application requires to authorize a sale through the payment gateway.

The specific tools don’t matter. If you don’t like Cucumber or RSpec, use whatever tools or methodologies work best for your team. However, the point is that the implementation details are based on the user story, but aren’t prescribed by it. Instead, the implementation (or specifications, if you prefer) are details to be worked out during the development of the feature in a collaborative fashion.

A User Story is one specific kind of artefact with the goal of describing the interface that the user expects from the system and that is why low-level details simply does not belong there. If you put them there, you are changing the intent of the artefact and it no longer fits the definition of a US.

Use other forms of specification to capture lower level requirements and design decisions. Exactly what these other forms should be is something that have to be resolved in your organization and customized to your specific environment.

Your question sounds very similar to something like

I have this CarFactory and I need to have it make Bicycles as well, but our OOD “Guru” says I’m not allowed to do that. What is this BS!?!

Respect the separation of concerns and cohesion of your artefacts, both the ones in your code and the ones in your processes.

Make your own decisions

The answer to ‘So how actually can developers ever develop a story if there are no lower requirements?’ is very simple – the detailed requirements that are orthogonal to the needs of the end user (e.g. DB constraints, fields validation, etc) don’t actually matter to the user. If the user needs can be met by very different fields validation, very different DB structures or perhaps even no traditional DB at all, then it would be counterproductive to have the users make up such information with a particular implementation in mind, which may be very different from how the system is implemented in the end.

You’re professional developers, so make professional decisions to the best of your ability about implementation details. An user who wants a table can tell a carpenter what type of wood they’d like, but the carpenter is expected to decide how thick the table legs should be to handle reasonable loads. If you lack some information to make a meaningful decision, then that needs to be discussed with the user, but some 90% of content for a detailed requirements document actually does not need any information aside from the vague user stories common sense and industry best practices.

All those details aren’t arbitrary – there are bad choices and better choices, and they should be documented since they affect other parts of the implementation, but in the end they are still implementation details that can and should be decided by the implementing team according to user needs and best practices.

A standard car analogy – if a customer wants the car painted red, then an appropriate clarification for the user story would be to ask which shade of red would be better, but not the chemical composition of the paint; nonetheless it would be expected that they wouldn’t choose to paint the car with watercolors that would wash out in the rain, since it’s best practice not to do so.

Lots of good answers here. Hopefully I can add some value with another one…

I think one hang up your team might be having is migrating from a non-Agile methodology.

That’s usually some form waterfall methodology and, in practice, that usually does involve trying to document all technical requirements before a line of code is written.

But that doesn’t always work. Often it doesn’t work. The reason? Because the requirements rarely align with reality. Things change. Hence the move towards Agile.

With Agile, the User Story is all that the user cares about. They want to get form point A to point B. How to get there in terms of implementation is in your hands. If you’re waiting for someone to tell you the technical requirements, then that’s not really Agile. If you have questions, ask. If you need documentation, document, but you don’t want the customer making all of these decisions for you. They may have opinions, but in an Agile environment those opinions should be (as your guru suggests) discusses in a conversation.

It may feel that this is a burden to your team, but consider it a luxury. Your team now has a lot of say in the solution–which wasn’t necessarily the case in the waterfall model.