Our team is starting to refine a set of stories that cover components and UI as part of an upgrade to a newer version of Angular. These components will then be used to recreate screens in an existing application. We are considering this work technical debt.

Is there a recommended format for writing technical debt stories?

We use the "As a ... I need to ...so I can ...", as well as Gherkin's "Given > When > Then" acceptance criteria, for our standard stories that are more directly customer focused.

Is there something similar that should be used for these tech debt stories? Or should we just list technical requirements?

  • 1
    Do you have a set of user stories that capture the application that are you upgrading and converting? If so, are these user stories still valid? – Thomas Owens Feb 8 '19 at 13:31
  • 6
    Technical debt is a developer concern, as such it needs to be phrased in a way that makes the case that it is truly debt, and that debt is hurting the product in some way. Particularly if it is something that has to be done before you can start working to enable new features. Beyond that, there's no recommended format. – Berin Loritsch Feb 8 '19 at 13:34
  • @Thomas Owens - Good point. The more I think about it, I believe the set-up of the new version of the app, which has been completed, would've been technical debt, but perhaps the development of these components should be handled in standard user stories. – Bheitzer Feb 8 '19 at 14:17
  • @Berin Loritsch - Thanks for helping clarify this in my mind. This particular statement set me straight: "Particularly if it is something that has to be done before you can start working to enable new features." – Bheitzer Feb 8 '19 at 14:27
  • 1
    It sounds like you are struggling to justify the upgrade to a newer tool which will not bring anyone immediate "business value". Can you think of an impediment the new version will lift? Calling this "technical debt" already seems like a stretch to me. You just want to get your hands on the new stuff, right? How about "As a developer I want this new goody now in order to boost my morale". – Martin Maat Sep 16 '19 at 9:23

The roadblock you're running into is there by design, and you're running into it for the correct reasons.

User stories are things the user cares about. That's why it's written from the point of view of the user. If you can't express your task as a user concern, then it likely isn't a user concern, which is likely the case here. As far as the user can see, before and after the technical debt task, the same functionality will be maintained, so the user doesn't care what happens behind the screen.

Technical debt is a developer concern. It's something you care about, but which doesn't really add functionality that the application otherwise wouldn't have.

Note: If your technical debt causes an inability to implement a particular feature, then the resolution of that technical debt is inherently part of that feature/user story, at which point the current question is moot as you already have a valid user story.

User stories, and the enforcement of describing tasks as such, forces the workload to be user oriented, which is where the real business value lies for most companies (functionality/features leads to user happiness, which leads to customer acquisition). In this system, technical upgrades can only exist if they allow for adding additional features/business value.

And this is where the crux of the issue lies: what is the business value of your proposed technical upgrade?

  • If it adds functionality that the user wants, that functionality is the user story.
  • If it's about maintainability (i.e. future tasks can be implemented faster), the cost and effort spent on this should come from the company investing in itself to simplify its future workload. You should note that the user does not care about that (it's not a feature!). This is not a user story and shouldn't pretend to be one.
  • If it's about security, then it falls under the purview of security. This isn't always easily expressed as a user story (e.g. the average user doesn't care about using HTTPS). It can be expressed as such ("as a user I want to securely interact with the application") but it's also possible that this security concern does not come from the users but rather your company (at which point we get back to the company investing it itself from the previous bullet point)
  • If it's about performance, then that can be construed as a user story within reason. Users don't care about nanosecond optimizations. Users do care about multi-second performance improvements.
  • If it's about modernizing the application's UX, then you've got a clear user story: a nicer look and feel. Whether this counts as business value is contextual; how much is your company (and by extension its customers) interested in aesthetics of their product?

But the biggest bullet point, for which this roadblock was almost explicitly created, is developers doing something for themselves, e.g. wanting to play with the newest toys. While you can argue that there are indirect benefits (developer morale, keeping developers up to date, ...), there is usually no real added business value. If there were, you'd be able to easily express the business value as a user story.

In short, your inability to describe the change in function of its business value (= user story) suggests that there is no added business value. In a user story driven environment, this is the exact scenario that is intentionally being blocked to not waste development resources. Asking how to phrase it as a user story would be telling you how to circumvent the intentional checks and balances that your company chooses to operate under, which is not a good way to approach this.

If you need to circumvent the usual precedings (user stories), you need to talk to the project management about the upgrade and its indirect benefits that are not related to business value.

We use the "As a ... I need to ...so I can ...", as well as Gherkin's "Given > When > Then" acceptance criteria, for our standard stories that are more directly customer focused.

Note that this isn't exclusive to user stories. This format can be used to express developer concerns as well, e.g.

As a developer I need to implement dependency injection so I can lower future debugging efforts by using mocks / unit tests.

If this format is the only requirement, you don't actually need to use user stories for this. But if your company restricts this to user-driven business value, then your technical debt is sadly ignored.

I'm not a fan of companies who don't look at developer concerns and are only interested in user concerns; but as a developer I'm not the one who makes the executive decisions and if that's what the company chooses to do, I can't overrule that.

| improve this answer | |

"Scrum Framework only describes what needs to be done, but does not enforce how it needs to be done." "User Stories are a great technique for capturing functional requirements in a ‘good enough for now’-manner that leaves room for further conversation. But Scrum doesn’t prescribe nor require them. Other techniques are fine, as long as they help promote three things:

  1. They make the Product Backlog understandable to the Scrum Team and its stakeholders. A stakeholder should be able to view the Product Backlog and have a good sense of what's coming up and in what order;
  2. The level of detail they demand should fit the uncertainty of product development. Items that lie further into the future should require less detail than items that are about to be pulled into a Sprint;
  3. They should foster an ongoing communication and conversation between the Scrum Team and stakeholders (which includes users);"

Both quotes from "Myth 4: In Scrum, the Product Backlog has to consist out of User Stories" on Scrum.org

You also may like to watch "Telling Better Stories" keynote by David Evans.


  • Backlog can have all kind of stories. In my teams I suggested three types: user, technical, research
  • You don't have to use ‘As a [role] I want to [action] so that [reason]’ format for a user story.
| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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