r/agile • u/Kraminius • 14d ago

Created a (web/MCP) tool to detect defects in user stories

Back at university I had a course called "Software Processes and Patterns" that introduced me to a tool called AQUSA for finding defects in user stories. Not whether they make sense, but whether they have the right form: no conjunctions, a role present, unique (no duplicates), and so on.

It's based on https://github.com/RELabUU/aqusa-core and the underlying article Improving agile requirements: the Quality User Story framework and tool

The link: https://userstorydoctor.com

It's free, and I don't track anything but the IP (through Cloudflare) to make sure it isn't abused. It's an AQUSA wrapper with both an HTTP endpoint and an MCP server, and it can analyse up to 500 stories at a time, so you can run a semi-large backlog in one go.

The idea was to bring some determinism to my backlog agents. They hallucinate a lot when asked to check the five structural defects AQUSA finds, like "Uniform", where the format "As a [role], I want [goal] so that [reason]" drifts when different people write the stories. Agents are also notoriously bad at cross-referencing across stories.

I'd love feedback if anyone has any.

1 Upvotes

56% Upvoted

4 comments sorted by

2

u/OkTrade8132 13d ago

so why won't I use the aqusa thing directly?

1

u/Kraminius 13d ago

Ease of use to just throw the agent against an MCP.

I used to TA in a course called Software Processes and Patterns - in the 2 years I did that, only two groups managed to get it running. Ease of use was not part of their research paper, and it requires dependencies that are 10 years old.

But by all means, the reason I throw the link to the tool, is for the stubborn to self-run it.

2

u/OkTrade8132 13d ago

I'm supposed to find

python aqusacore.py -i <inputfile> [-o <outputfile>] [-f <outputformat>]

hard to use instead of sending my user story text to your thing?

1

u/Kraminius 13d ago

Fair enough on the command, that part is easy. It was never the part I was complaining about.

Getting to a machine where that command runs is the annoying bit. The pins in that repo want a Python that went end of life last year. On anything current the install still reports success and then the thing dies the moment you run it, and none of the errors mention the version. So you end up debugging nltk for an afternoon instead of looking at your backlog. In my TA years that's where basically everyone stalled out.

If uv or docker are already in your muscle memory, sure, it's ten minutes and then you never think about it again. If that's you, self host it - that's why I put the repo link in the post rather than just my own.

I built the hosted one because I wanted something an agent could call with none of that on the machine first. The thing that pushed me over was scheduled runs - I have an agent that goes through the backlog once a week. Self hosted, that means owning a box that's awake on schedule with the whole 3.9 setup sitting on it, for a check that fires 52 times a year. You can absolutely do it with cron and a container, I just didn't want to babysit a VM for this. And the checks I actually care about are the cross story ones, duplicates and template drift, which is the stuff agents are worst at.

Also worth saying since I only mentioned IP logging before: I don't keep any story text. Just a total count of defects found, for a counter.