• Seilevel Team

    Here’s the Team

    Welcome to our Seilevel Photo Op.

User Stories and Technical Stories in Agile Development

A common problem that I have seen Agile teams grapple with is writing user stories and acceptance criteria for projects that are heavy on technical implementation and modifications with no substantive change in the user interfaces or workflows. This kind of scenario is very common in companies that are upgrading infrastructure or changing underlying design and architecture to improve performance or scale. These types of projects are typically referred to as ‘IT Driven Initiatives’ to distinguish them from projects done in response to some specific functionality requested by the Business team.

The User Stories written from the viewpoint of the functionality that users will need does not really provide context in terms of the work to be done by the development team. In most cases, the existing functionality will satisfy the needs of the user with no additional changes needed. The changes are taking place under the hood, as it were. Teams in these situations create user stories that are nothing more than technical implementation details. For example, it is common to see stories like this:

‘As SYSTEM A, I want to map the incoming Order XML to the main Canonical, so that SYSTEM B can consume the Canonical and run order validation rules against it.’

The acceptance criteria that are provided for a story like this will be filled with technical details on the Order XML, Canonical, validation rules and so on that need to be delivered.

The problems with this approach are readily obvious. There is really no context of what functionality is to be delivered from a user perspective or the expected outcomes from their viewpoint. An entire backlog filled with stories like this can easily become incomprehensible, especially in complex environments. Very soon, developers have no context of what they are building and most importantly, how it is going to be used eventually from a user perspective.

At Seilevel, we recommend using Technical Stories instead of User Stories in these situations. Technical Stories are best used in conjunction with User Stories, to complement them. The User Stories provide context to the associated Technical Stories so that the developers understand the functionality from the user viewpoint.

Continuing with the example above, it can be reformulated as a User Story / Technical Story combination as follows:

User Story: ‘As an online shopper at ACME Widget Company, I want to ensure that my order is complete and valid when I submit it at the online store, so that I can get the products I ordered in a timely manner without mistakes or delays.’

Technical Story: ‘In Order to ensure that only valid orders are accepted by the system, System A must map the Order XML to the main canonical and provide the main canonical to SYSTEM B to run order validation rules.’

In a real world scenario, there will typically be multiple Technical Stories needed to deliver the functionality required by the User Story. Technical Stories can be as granular and detailed as needed to ensure that the proper functionality is built. However, they will all tie back to one user story that the developer can quickly lookup to get context on why they are performing the tasks they are engaged in.

I typically tend to write the User Stories in these situations at a higher level or even use Epics, if appropriate. The Technical Stories are written targeting the team that will work on specific pieces of implementation or specific sub-systems. Acceptance Criteria are written to be appropriate for the context of the story – User or Technical.

For example, Acceptance Criteria for the User Story could be along these lines:

AC 1 – User must get a message if the order is valid that it has been accepted for processing.

AC 2 – User must get an error message if the order is invalid with prompts on the issues that must be fixed before it is accepted for processing.

And so on…

Similarly, acceptance criteria for the Technical Stories can be written appropriate to their context. For example:

AC 1 – The data from the Order XML must be mapped into the main canonical in accordance with the mapping shown in the attached spreadsheet.

AC 2 – Main canonical must be passed to SYSTEM B via interface A using API K and a success message received when the transfer is complete without errors.

And so on…

When the stories are split out like this, it becomes very easy to test the delivered functionality. In our example, simple regression tests can be written for the User Stories to ensure that the end user experience is consistent with current state behavior. Tests created for the Technical Stories will be qualitatively different and focused on functionality at a much lower level.

In conclusion, here are the key takeaways.

  1. Keep User Stories focused on the user experience and outcomes.
  2. Write Technical Stories to give context to the User Stories from a system perspective.
  3. Map Technical Stories to User Stories so that it is clear how the functionality being developed relates to the user experience.
  4. This technique is very effective for projects where the user experience or user interface does not change but the underlying technical infrastructure is being changed to improve performance, upgrade technology or other technical reasons.

Need a free consult to work out an issue like this? Contact us to discuss.

21 Responses to User Stories and Technical Stories in Agile Development

  1. Tushar November 18, 2016 at 12:07 am #

    Hi, thank you for this post I agree with you that most common problem that I have seen Agile teams grapple with is writing user stories and acceptance criteria for projects that are heavy on technical implementation and modifications with no substantive change in the user interfaces or workflows.. very useful information

  2. Warren December 15, 2016 at 4:53 pm #

    How is a technical story that is separate from, but related to, a user story different from a user story with associated technical tasks? In the case of your example, how is the technical story different from the following list of technical tasks?:

    * Map System A Order XML to main canonical
    * Provide main canonical to System B to run validation rules

    I think you’ve provided a viable answer, but it strikes me as being an alternative for what I understand to be the traditional way of elaborating the details of a user story. I’d appreciate any insight into the difference.

  3. Bob LIeberman September 20, 2017 at 5:32 pm #

    Ajay, I guess I don’t like this approach. Never been a fan of technical stories because they reinforce the development team’s already strong tendency to see work as build X build Y rather than solve customer problem 1 and customer problem 2.

    The vertical slicing approach solves the problem in a different and often better way. You devise a “tracer bullet” as its often called, which is a full stack story having minimal functionality at all the levels except the one where the technical work is. This captures the technical work and has the advantage of exposing the supposedly “done” technical component to real-life usage by a customer, if in a limited way.

    Could you comment?

  4. Ajay Badri November 4, 2017 at 10:01 am #


    Thank you very much for your comment. We are talking of two different approaches to solving the same problem. The reasons that I use the Technical Story approach as opposed to your preferred method are as below.

    1. I want to be very prescriptive of the technical approach to be taken to design or redesign a specific piece of functionality. This is typically done after consultation with the Enterprise or Solution Architects who are designing the system and the Technical Stories capture their design approach.
    2. The technical changes being made impact all or a significant portion of the ‘user accessible’ functionality that sits on top of the technology stack. For example, a complete redesign of a Loan Application and Adjudication process. A project of this nature can easily stretch out over two years or more, depending on the complexity of the underlying system being changed. Writing user stories for each step of the process and then associating technical stories at specific points becomes very inefficient from a time and effort viewpoint. In these situations, I will typically write User Stories at the level of an Epic or Feature and associate multiple Technical Stories with them.
    3. I want the Technical Story to be tested to ensure compliance with the specified design. Since the overall functionality does not change, tests of the functionality from a user viewpoint will not guarantee that the functionality was implemented as designed – unless it is broken of course and nothing works as expected :). When there are hundreds of specific technical implementations to be tested in the lifecycle of the project, it is a lot easier for the test teams if they are dealing with the actual implementation expectations in story format with the containing User Epic or Feature providing context and baseline information.

    We can get there with your preferred approach and if that works for your organization, stick with it. But there will be a point where I believe that the ‘tracer bullet’ approach will not scale anymore from the viewpoint of the analyst who has to create the underlying artifacts – user stories and technical stories. If you get there, give this approach a shot and see if it works for you. Thanks for the comment and keep the conversation going.

  5. Ajay Badri November 4, 2017 at 10:20 am #

    Hi Warren:

    Apologies for the belated reply. I guess I missed the notification of your comment earlier and saw it when Bob commented a couple of days ago. But, better late than never, so here goes…

    I write Technical Stories in very specific situations, typically when there is a rewrite of an existing system with very minimal or no change to the functionality at the user accessible level. In these situations, I care about the very specific way in which a technological implementation or change is made. If we were to take the most basic interpretation of a user story in the context of a backlog, when the functionality already exists and has been in use for several years, the development team will be well within their rights to reject the story since it has already been delivered years ago. We get around this by giving them a Technical Story that spells out clearly the change to be made in the technology stack even though the overall functionality is unchanged.

    Further, by writing a very prescriptive Technical Story I can ensure that the test teams sign off on a very specific change that will not be visible at the user accessibility layer. This is particularly important in large scale technology refresh cycles where the changes build incrementally over time. If the initial implementations are not per the design then later changes will need to be modified or in a worst case, not possible at all depending on what was done initially. In these scenarios, the Technical Story is the ideal artifact to communicate these intentions to the entire project team.

  6. Ajay Badri November 4, 2017 at 10:27 am #

    Thank you very much for your comment Tushar and glad you found the article useful.

  7. Prasoon January 8, 2019 at 2:49 am #

    Hi Ajay,

    Found article very helpful & relevant..appreciate your efforts to respond queries /clarifications

  8. ankit shivhare March 8, 2019 at 12:08 am #

    Hi Ajay, It is late read but it helps. Being a Business Analyst I do not see any importance for writing a technical user stories since they may not be testable. The approach should be to have the solution in place for building system but not to complicate it using the technical user stories. What if solution changes and in between the sprint somebody need to spend the time to update the user stories.

    Any ways just wanted to clear the thoughts on:

    Q1: Who spends time in writing the user stories?
    Q2: Are they testable from your pov?

  9. ankit shivhare March 8, 2019 at 12:09 am #

    Hi Ajay, It is a late read but it helps. Being a Business Analyst I do not see any importance for writing a technical user stories since they may not be testable. The approach should be to have the solution in place for building system but not to complicate it using the technical user stories. What if solution changes and in between the sprint somebody need to spend the time to update the user stories.

    Any ways just wanted to clear the thoughts on:

    Q1: Who spends time in writing the technical stories?
    Q2: Are they testable from your pov?

  10. Nirman Doshi May 17, 2019 at 8:59 am #

    Found this article very useful, and yes, having technical story in the backlog makes more sense in the scenarios you have listed. Along with that, project setup (that is, creating a solution, designing bare minimum project classes, etc) are key activities for any project and starting point of development. I am not sure if it is even possible to write in a form of user story which business can understand. Also, it is not testable. And so, I would prefer to use your approach in this case.

  11. Ajay Badri June 29, 2019 at 1:36 pm #

    Hi Ankit:

    Thanks for your comments and viewpoint. Please find below my responses to your questions.

    1. The analyst(s) who is working on the project will write the Technical Stories / Features. Depending on the size of the organization and the way teams are structured, it could be the same person who creates the User Stories / Features and the Technical Stories or an analyst attached to the development team will write Technical Stories / Features and associate them to their related User Stories.

    2. Yes, both the User Stories and Technical Stories will be testable. In the scenario I provided in the article, the User Stories will be tested as part of standard user acceptance testing or regression testing (assuming that there is no functional change and only an underlying technology change). The Technical Stories are testable at a granular level during the development phase.

  12. Vijay July 17, 2019 at 1:53 pm #

    Can you please provide a sample technical story which includes interface request and response data mapping etc. along with other technical details such as the security protocol etc. In a traditional way, we cover all of these details in a system interface document which typically include technical flow diagram, request/response data mapping, samples, schema/wsdl etc. So wondering how to cover such as details part of technical user story. Sorry for being too detailed. I am pretty new to this approach.

  13. Ajay Badri August 25, 2019 at 2:01 pm #

    Hi Vijay:

    Thanks for your question. To clarify, I am not suggesting that Technical Stories or Features are a substitute for a system interface document, technical flow diagrams, request / response data maps, etc. This is not an either / or proposition or mutually exclusive set of artifacts.

    Think of it this way – the technical story or feature written at a higher level can be fleshed out by lower level stories or other artifacts that you have listed in your comment. For example, a Technical Feature / Story can be written like this – IN ORDER TO enable a sales user to submit valid orders for processing / shipment, the Order Domain WILL NEED TO provide a verification solution that will test all orders for validity prior to acceptance, SO THAT only valid orders are accepted for processing.

    This Technical Feature / Story can then be elaborated with a system interface diagram, interface mapping, validation rules, and so on to deliver the requested functionality.

    I hope this helps.


  14. Victor Garcia January 23, 2020 at 9:48 am #


    Thank you very much for this post that precisely addresses an important issue that we need to face in my current team.

    I totally buy the idea of Technical Stories, however I think that the example given is not maybe the right one.

    Every business-focused vertically-sliced User Story will be necessarily broken-down into technically-focused tasks that represent the job needed to be done in the sprint by the deveopment team in order to achieve this User Story. But this is not where we need an artifact like a technical story. This is just plain development (mostly technical) Tasks, related to their parent User Story.

    As you precisely pointed out, we need something like a Technical Story when nothing changes for the user, that is, a typical system refactoring to improve scalability or robustness. Moreover, this kind of work not only does not have a related business requirement (because as we said, nothing changes in the surface), but typically may affect not only a business functionality, but maybe many of them, maybe even all of them. Including the closed ones.

    So I dont see how a Technical Story should be related to a parent User Story.

    In my team we need to do this because we have a ton of work for building a new platform, a technology change, where the actual functionality will be kept and maybe new one will be added, but mainly we will keep the existing functionality. The change should be transparent to the user.

    This is a lot of architecture planned up front before starting to add chunks of end-user functionality.

    This is where we see the utility of using Technical Stories, just because there will be NO new User Stories in the first sprints. When new User Stories emerge, all their related technical job to achieve these increments of end-user functionality will be defined just as regular Development Tasks, children of the stories.

    And in the meantime, every refactoring initiative, that by definition means changes in the system, not in the user functionality, will be addressed through a Technical Story.

    Does this make sense to you?


  15. Ajay Badri February 23, 2020 at 9:33 pm #


    Thank you very much for your thoughtful and considered comments. I believe you are referring to core capabilities that your team is building to support capabilities that are required by the business. For example, a 2 factor authentication requested by business will need some basic capabilities like the ability to create a token, validate a token, send a token, etc. These core capabilities are then stitched together into orchestrations that tie together the different core capabilities into a user experience or workflow.

    It is perfectly okay to write ‘stand alone’ technical stories for all the core technology that is built to support business requested capabilities that manifest as ‘User Stories’. My only point is that eventually, these core capabilities must also be tied to business requirements. The sequence in which these relationships are made is not as important as actually making them. For example, if it may make sense for your team to work in this cadence.

    1. Create technical stories for core technology
    2. Create technical stories that tie together core technologies into workflows
    3. Create user stories
    4. Relate user stories to the previously created technical stories

    The relationship to business requirements is critical. Absent that, you have no rational way of tying back functionality that is being built to actual user experiences. Whether the business requirements are pre-existing (technology refactor scenario) or brand new (greenfield development), any functionality that is delivered needs to be validated against business requirements and capabilities. Without over arching business requirements and the value associated with these requirements, prioritization becomes very difficult, if not impossible. The more capabilities you build that are not explicitly tied to business requirements, the greater the risk of a runaway project.

    It is for this reason that it makes sense to tie any and all technology that is built (refactoring or green field) to business requirements. Absent that there is no business justification for any effort and that is always a dangerous place to be come budget time :-). Practical considerations may result in some disconnect between technology and overlaid business requirements. But the longer the disconnect, the greater the project risk. If your teams are a few weeks ahead of business requirements, it is not ideal, but manageable. But if you go for months without business requirements to tie to technical solutions, it is a very risky proposition.

    Hope this provides context for my recommendations.

  16. branko drazenovic April 5, 2020 at 7:30 am #

    Why complicate things unnecessarily, why not just use Use Case(s)?

  17. Ajay Badri April 5, 2020 at 5:49 pm #

    Thank you Branko for the question.

    Use Cases are a great model to define the interaction between the user and the system. However, they are silent on the implementation details (as they rightly should be). Use Cases can be used instead of user stories if your organization or team is more comfortable with this model AND your system has a lot of user to system interaction. However, you will still need Technical Stories to define how the functionality described in the Use Cases will be delivered.

    This is the rationale for pairing ‘User Stories and Technical Stories’ in my article. If you want to pair ‘Use Cases and Technical Stories’ (pursuant to the caveats I have identified) that is certainly a viable alternative. But Use Cases alone may not be sufficient to get the outcomes you desire.

  18. Angshuman April 9, 2021 at 7:29 am #

    Hi Ajay,

    Let’s say team is developing an application that has 5 buttons. Each button allows user to invoke an operation. These functions would be implemented in separate libraries. Also there would mechanism how those libraries communicate to application (e.g. whether whether the function can be invoked or not, provide notifications, etc) These buttons and the application overall has many user experience features like animations, touch/stylus support, drag drop reordering, etc.
    How should we typically create stories for this case? If we create stories like – “as a user I want to invoke the operation A”, “as a user I want to invoke the operation B”, where do we include the work related to developing the application, communication with the library, UI look and feel, etc?

    Secondly, if creation of the library for operation A completes before the UI, how can that be demoed? Can we have a generic button in the UI that simply invokes the operation (and may be a message box that shows a notification message). (Let’s assume that the plan is to have an animated image button to invoke and an animated status area in the application to show the notification)

  19. Jacque April 29, 2021 at 12:06 pm #

    Hi Ajay! This is a great article and is very helpful in designing data analytic projects. We are typically getting users stories how how they want to see data in a report format but from a build perspective – it is building the data model that is taking up the bulk of the work….

    I’m hoping you can provide me an example of creating a users story (reports that a user wants to see) – technical stories to build/modify the data model / then report stories to actually build the final output? I’m a very visual person and I’m just trying to form that picture in my head.


  20. Krunal Parikh April 30, 2021 at 8:05 am #

    Hi Ajay,

    It is a great article to understand the user stories and technical stories and how we can map them in order to have quality product. However, I am currently working on purely backend and infrastructure based project. So, I would like to understand how can I write technical stories in below projects:
    – One project which requires the purely API implementation and backend set up in node.
    – One project requires infrastructure set up of AWS services like kubernetes.


  21. Emma Jean September 21, 2021 at 3:12 pm #

    if you create a user story that states the below, do you have an suggestion on how to best write the user stories? Our user stories can be no longer than two weeks. All the tasks to complete the actual business requirement takes longer than two weeks. CRQ process takes two weeks by itself. I have been copying the business requirement and putting stretch goal on it or creating stories for dev, testing and CRQ process. Is there a better way to break the stories down?

    As a User I want a list to see all my active books so that I can add a new category to each book.

    This change requires:

    a business layer,
    a data layer,
    a service,

    Unit testing
    Create Test Cases/Scripts
    Execute functional/regression testing
    Execute UAT Testing
    two week turn around for CRQ Process

Leave a Reply

Your email address will not be published. Required fields are marked *