In my work, which is a UK university, we currently have no specific way of recording and tracking business logic and rules as they arise from stakeholders for our in-house software projects.

We use Agile Scrum and put things into the usual product backlog items, etc. but the logic is often clouded in multiple different items and its clarity is then lost. This then causes confusion later and the stakeholders sometimes say "we didn't ask for that" when they did, and vice versa.

I am fairly new to the team and a junior developer so not involved in the BA side but want to prevent us getting stung again in future.

Is there a good way or single repository or even dedicated piece of software that handles this?

Any thought would be greatly appreciated.

PS We currently use Azure DevOps as our main software for managing projects. Thanks

  • 1
    Are the issues simply about requirements not being clear? Eg. one guy telling you that is not what he asked for. Or is it about different groups of stakeholders giving you conflicting requirements? Eg. You implement one guy's request, only for second guy to come and request you change it, frustrating the first requestor?
    – Euphoric
    Commented Jul 3, 2023 at 5:00

3 Answers 3


We use Agile Scrum and put things into the usual product backlog items, etc. but the logic is often clouded in multiple different items and its clarity is then lost. This then causes confusion later and the stakeholders sometimes say "we didn't ask for that" when they did, and vice versa.

If you’re doing scrum, every task falls under a story and every story is reviewed by a stakeholder and has an acceptance test. If not then the product owner isn’t doing their job. This is why they review the backlog.

“We didn’t ask for this” should only come up when you can say “you asked for that. That’s why you get this”

Demos do show people surprises. Scrum already has all the tools to trace work back to how it got requested. But nothing will ever ensure there are never any surprises. Sometimes people just won’t see how asking for X requires Y until you show them Y. At which point they finally tell you about Z.

Which is exactly why we demo early and often.

  • Ah yes, you remind me - our management have let the product owners go so we're just a team of Devs trying to do everything (badly at present). Maybe therein lies the answer. Actual staff to do these jobs. Commented Jul 3, 2023 at 14:26
  • 1
    So many teams forget that agile is not a dev team thing, it's a company philosophy thing. Commented Jul 3, 2023 at 14:32
  • 1
    @StephenBeale if you guys do the job you won’t need the extra body. Get in the habit of asking what work traces back to until people get the hint. Commented Jul 3, 2023 at 19:00

I think Azure Dev Ops (old name: Team Foundation) does handle this as long as you are using the tasks/bugs/epics etc

If A feature is requested, Make a Task/Story/Epic for that feature with detailed note from the meeting etc. Then link your PRs to that task.

If any questions come up about a section of code you should be able to work out which PR added that section and work your way back to the original Task with all the notes ie. "requested by X for reason Y"

Generally though, you want to try and avoid this confusion. Keep the request and the delivery close together if possible and if not remind people: "This sprint we are aiming to deliver feature X, which Y requested and will solve Q. This has the side effect of Z which has been signed off as acceptable"

  • 1
    Thanks for this. Yes, we are doing this in effect but I was wondering if there was a way to view the logic at a high-level outside of these tasks/bugs/epics etc as they become very granular with a focus on code and, I feel, lose sight of the bigger picture. Cheers. Commented Jul 2, 2023 at 11:45
  • 1
    ¯_(ツ)_/¯ I mean if you dont write things down, you don't write them down. my advice is to write them down. My additional advice is to remind people what they asked for before you give them it. You could also try shorter sprints
    – Ewan
    Commented Jul 2, 2023 at 11:52
  • also maybe do you use "sprint goals"?
    – Ewan
    Commented Jul 2, 2023 at 11:53
  • we do use goals, yes. I suppose I am thinking along the lines of Gherkin/Cucumber but not expressly for testing. Thanks again. Commented Jul 2, 2023 at 12:09
  • If looking at a new area of the code, how do you get a picture of all the Zs that have been signed off on? Do you expect people to track down and read potentially hundreds of tickets? Commented Jul 3, 2023 at 1:46

"We didn't ask for that"

As SM, these claims would raise a red flag for me. Something is going wrong with the communication and/or the Scrum implementation. They could be a good reason to start doing retrospectives at the end of every sprint and discuss these matters.

If you are doing professional Scrum, events should give you enough opportunities to perform control checks along the sprints.

If you aren't doing professional Scrum, it's an opportunity to learn about the framework, the SM role and bring these issues to the table yourself and get the whole team involved because the solution cannot depend on a single person.

Back to the core question, you could add a CHANGELOG.md file to the source code. Something along the lines of this1, but enriched with issues' ID, sprint goals and number, etc.

The alternative is placing this information as SCM comments. Some SCMs allow links to issue trackers (Jira, Redmine, Asana, etc.). However, I don't think SCMs can give you the best support to format and search the information as you need it.

The advantage of the changelog file over comments is, essentially, the format. It's plain text. You can format it and arrange the info as deemed best. SCM's text searches will complement the results (files with code) with literature (changelog's entries).

Also is a single "file-to-go" vs "go the issue tracker, then the SCM and then the source code".

Side note: This Changelog file is not supposed to be public as those we see in public SCMs or Official websites. Not even for stakeholders. The only audience of the file is the Scrum team. More specifically, for developers.

1:Only for illustration or guidance. Adapt the format, the content and the literature to the needs of the team.

  • If you use a changelog/issue tracker, how do you maintain a big picture view of the current requirements, once the number of issues hits the thousands or tens of thousands? Do you expect everyone to read the hundreds of prior issues that are relevant to any single area of functionality, and somehow discern which are still relevant and how they interact? Commented Jul 3, 2023 at 1:42
  • The changelog doesn't track every single commit or little change of the code, only the relevant ones to allow you to "draw" a timeline for epics or stories and see their evolution over time. Changelogs usually put the recent changes on the top, so the most recent info and state of the source are at the beginning of the file. The big picture of a feature must be gathered by searching through the file as you would for through the issue tracker. The main difference is that you are doing it in a SCM which allows you to inspect the code in a retrospective manner while consulting the changelog.
    – Laiv
    Commented Jul 3, 2023 at 6:30
  • The overall picture you want to see at a single glance is complicated at the scale of thousands of issues. It will take an effort from you all to keep the traceability and documentation up to date. Either you draw it (diagrams) or you write it (changelogs, issue trackers, reports, etc) it's additional work. The length of this info and how accurate and up to date should be, depends on what you need it for. For example, my changelogs help me to know what has been added, removed or deleted to the big picture. The whys are links to the issue tracker.
    – Laiv
    Commented Jul 3, 2023 at 6:37
  • As for the linked example for the changelog. Take it as a reference, if you find a format that works for you, then go ahead. For example, you could sort the entries by features, or epics and for each one, apply the suggested notation added, deleted, fixed, etc...
    – Laiv
    Commented Jul 3, 2023 at 6:41
  • 1
    An alternative is the team commits to maintaining the current state and reasoning organized across multiple files (like we organize our code) in a system that actually supports organization, diagrams, and full text search with stemming. Getting the team to commit to any documentation other than the issue tracker is a different problem though. Commented Jul 8, 2023 at 1:45

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.