Beyond If’s: Approaching the Gilded Rose Kata holistically

The Gilded Rose kata is everywhere (great source here). But most posts mainly focus on refactoring if-statements to reduce cyclomatic complexity, which is valuable but misses the bigger picture. After leading AI product development for an AI assistent serving 200,000+ employees and modernizing legacy systems, I’ve learned that how I approach a problem often matters more than the solution itself.

So let me take the kata and show you. Let us start with a simple question: What is Really wrong here?

When I first opened the Gilded Rose kata, my reaction wasn’t “let me fix these conditionals.” It was confusion. The structure is unclear. Test fixtures live in the root folder instead of a proper tests directory. There’s no clear entry point, no Makefile, no automation. These aren’t just style issues – they’re friction points that compound cognitive load.

Still, I dove into it for a few days. Wrote tests, added automation, metrics and iterated on assumptions driving improvement. After a few days, I started looking at what others were doing. Surprisingly most kata solutions jump straight to refactoring without asking: what is this project actually for? And am I measurably improving it? Coming from both development and product management, I know you can’t improve what you can’t measure.

Based on my experience transforming financial platforms and IIoT systems, here’s the systematic approach I now apply to unfamiliar codebases.

Step 1: Understand How Lost We Really Are

Before touching any code, I measure basic operations:

How long does it take ME to run the program? I.e., after opening, can I quickly e.g. call uv run src/main.py or do I have to search and parse through multiple locations?
How long does it take ME to run the tests? I.e., do they run at all? Do I understand them?
Is there a README, Makefile, or equivalent? To me, these are anchor points, entries to the domain and the solution. If they are not there, there is something amiss.

In the original Gilded Rose, these simple questions revealed immediate problems. No automation, confusing structure, unclear entry points. This tells me where the real work needs to happen first.

Step 2: Make a Map – Where Are We, Where Are We Going?

Since diving into Wardley Maps I have began to love these questions of where we are and where we are going. Thus, I established baseline metrics using modern Python tooling. When I ran this on the original kata:

Ruff: 44 errors flagged
Radon complexity: GildedRose class scored C (11) – clearly problematic
MyPy: 25 type errors across both files. That is a lot for just two tiny files.
Test coverage: 100% for the main file, but only end-to-end tests. So basically, the test works from the highest possible flight level. No unit tests. No clear flag where something is amiss.

Now I know objectively where I am. But equally important: where do I want to go? Do I want to learn ports and adapters? Practice domain-driven design? Write more pythonic code?

I suggest phrasing this as a set of questions I can answer with Yes or No. Think AWS’s narratively structured 6-page memos – what reduces confusion and cognitive load?

Step 3: Apply, Refactor, Test, Learn, Iterate

Only now do I start the typical kata work. But with clear objectives, every decision has purpose. I restructured using modern Python practices – uv for dependencies, pre-commit hooks, proper structure. If you need an opinionated example: https://github.com/swkBerlin/kata-bootstraps

The refactoring itself became strategic:

Separation of concerns through composition over inheritance
Unit testability by breaking down the monolithic update method
Type safety to catch errors at development time
Clear domain language using ubiquitous language (think Domain Driven Design) that business stakeholders could understand. Because in the end I code for customers and stakeholders, not only for my own happiness.

I’m currently experimenting with Ports and Adapters (hexagonal architecture, though it has nothing to do with hexagons), so that is what I have tried here.

You can see my current state of solution here on Github: Beware, this is WIP, or better LIP, Learning-in-Progress.

Some example solutions that I found helpful and great:

https://medium.com/@gabriellamedas/the-gilded-rose-refactoring-kata-2dd2d6f52601
https://sourcery.ai/blog/refactoring-gilded-rose/
https://www.johngerace.com/gilded-rose-kata/

Step 4: Know When to Stop

100% coverage helps nobody. What am I certain about that must be tested? What’s highly valuable to customers? What’s intentionally broken or just a PoC? Here the Product Manager in me came up.

Is this a PoC? Than focus on the value stream and hypothesis testing. I will throw it away tomorrow, so vibe coding without tests is fine.

Is this a production grade solution? TDD, DevOps, DDD, whatever XDD you need to reduce both your cognitive load and the risk you are taking should be applied. Not dogmatic, but pragmatic in a holistic way.

In this case, I used pytest’s skip/xfail for intentional (!) technical debt and focussed testing on high-value, high-risk areas. Perfect is the enemy of good.

Step 5: Forget Everything I just said and Enjoy the Kata

Kudos to my yoga teacher for the “Forget everything I just said”.

Sometimes the best learning happens when you stop optimizing and just play.

This is a Kata. Nobody needs to go the lengths I did on it. If you found others going even further, please leave me a message. Looking forward to it.

The Structure I Actually Want

For any kata, I now bootstrap with:

Folders: src, test, docs in root
Tools: uv, Makefile, pre-commit
README that points to docs, explains how to run (Makefile command), and gives the value proposition

My suggested resources to check out:

for opinionated base structures: https://github.com/swkBerlin/kata-bootstraps
astral-sh‘s Python tooling ecosystem. Fast and helpful. Also: code styling must be automatic.

What I’m Really Learning

The meta-insight isn’t merely about design patterns – it’s about applying product thinking to technical decisions. Every refactoring choice should answer: “Does this reduce confusion and cognitive load for future maintainers?”

This systematic approach has served me well, from proposing and architecting AI solutions to leading cross-functional teams through agile transformations. The kata becomes a microcosm of real-world technical leadership. This may grow into applying Wardley-Map-like strategic thinking using the OODA loop.

What’s your approach to legacy code katas? What learning has surprised you there?

Share your thoughts below.