[Summarized answers inserted] When working in a feature branch and I find code that should be refactored that is not related to the branch aside from the fact that it is in the same file I am working in.

Should I create a new user story?

  • The consensus is that there should indeed be some sort of new PBI covering the refactoring. [User Story, Bug, Issue]

Also how do you write a user story for refactoring code?

  • Referencing @DocBrown comment, How to work on not User Story related tasks.
    • You should indeed structure refactoring as a User Story and make an effort to put it in these terms to focus on its potential value to the business.
    • Citing reasons like: Technical Debt and How the responsibility of refactoring is inherited from the past feature that did not meet quality standards, therefore never should have met the Definition of Done

In the case of smaller fixes, does it justify creating a PBI and a branch to fix?

  • As answered by @DanCornilescu, There are reasons for separating the fix from the current work in progress such as, creating unnecessary conflicts in your branch, or creating a distraction from what your were supposed to be doing.
  • Also added by @DanCornilescu is the value added when working on teams. If fixes are addressed in a personal branch and not added to Project management, other devs may make the same fixes.

Would it be poor practice to just try and and find the closest relating user story and shoehorning a task in?

  • It would seem, that giving an answer to this can only be done on a case-by-case basis. Although based on the preceding arguments, it seems it would be worth the effort, if you cannot find an appropriate place to add your new requirement then it should probably be verbalized in a new User Story.
  • I also want to reference the answer by @S-Lott from What is the best way to handle similar functionlaity in separate user stories / Product back Log Items? to reminds us that User Stories are not features and how it pertains to "shoehorning".

2 Answers 2


Personally I'd just file an issue for tracking it, to be fixed in the main development branch (or wherever such items are addressed in your larger project/org), for several reasons, all ultimately translating into adding more obstacles to overcome for your very own feature:

  • any unnecessary change in a feature branch could create unnecessary conflicts in future branch merges, including for your own feature branch
  • it's a distraction from the agile methodology point of view, you'd waste your time doing something else than what you were supposed to do for your feature

Other developers touching the same file are likely to notice the need for refactoring as well, in their own feature branches. With a policy of open season for such work it's likely some will jump on it as well, causing more trouble than good due to conflicts. Thus having a tracking issue is very important:

  • refactoring is visible and not forgotten
  • refactoring will be done w/ proper planning, establishing the story it belongs to, who will do it, when, in which branch/release, etc.
  • everyone is on the same page
  • I upvoted because I agreed with everything here except the side comment. I don't necessarily disagree with the side comment, I just don't have enough experience with feature branches to know what you're talking about. Can you elaborate?
    – MetaFight
    Commented Feb 18, 2017 at 15:34
  • 1
    @EsbenSkovPedersen Work in progress can be committed daily (or even more often than that), even to the main branch (well, once the mindset is right), as long as it doesn't break existing stuff. Feature toggles are your friends. If you're not integrating for weeks - you're not really doing CI. Also, what's the point of deploying something (WIP or not) if it's not yet integrated? What does that prove? You'd have to re-do it after integration anyways - later, more expensive, higher risk, etc. I know, it's not impossible - it used to be the norm a decade ago. But nowadays we have CI... Commented Feb 18, 2017 at 18:26
  • 2
    I'm not sure I agree. You assume having to use a feature switch isn't a sacrifice. In my book it is. The way I see it, you're just trading one set of sacrifices for another and then being dogmatic about it.
    – MetaFight
    Commented Feb 18, 2017 at 19:00
  • 1
    @EsbenSkovPedersen There are ways around it - I designed one myself, exactly for preventing such breakages. But we digress and I'm not sure this is the right place for such discussion. Commented Feb 18, 2017 at 23:17
  • 1
    @DanCornilescu I appreciate the added portion about development teams. I myself work by myself so I would have overlooked this and think it makes for a stronger answer for those other than myself. Commented Feb 21, 2017 at 13:59

Cross posted my answer...

The answer depends on how the team is using User Stories and Tasks, and their approach to refactoring.

Associating Work Items to Commits

If they have an arbitrary policy that forces you to associate commits to Work Items, then you'll either need to override the policy or associate it. Often this association is required for some kind of release report so that all changes in a release can be seen. Perhaps the team is using associations to track time on task? If so, create a Task to associate the commit to. So, the answer depends on how the team is using the association. In the past, I have used a User Story "Improve Component X" to associate refactorings to. This User Story remains open as a place to track improvements. My general advice is to do avoid unnecessary effort (e.g. creating Tasks when they are not actually being used for anything of value) and do the simplest thing possible. You want to make refactoring as easy as possible.


Does the refactoring need to go into the mainline at a different time than the feature? If so, you'll need a separate branch. If the refactoring can go in at the same time as the feature, keep things simple and refactor in the feature branch. I would at least use a separate commit for the refactoring.

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.