Technical Debt by Impact

• 

Inspiration

Technical Debt by Impact is built on proven software-engineering research, not a vague AI scoring trick. The idea comes from CodeScene’s hotspot-based maintainability work and the paper Industrial Code Quality Benchmarks: Toward Gamification of Software Maintainability, which shows that technical debt becomes truly expensive when poor maintainability overlaps with the parts of a codebase teams change most often.

That insight matters because most static analysis tools still treat every warning as equally important. In real teams, it is not the ugliest code that hurts most. It is the ugliest code in the busiest parts of the system. We wanted to bring that industry-proven hotspot model directly into GitLab merge requests, where teams already decide what ships.

There was also a practical motivation: this kind of impact-aware maintainability analysis is usually sold through premium SaaS tooling. Technical Debt by Impact brings that capability directly into the repo and into the review flow, including for private and closed-source projects, without requiring a separate platform or separate workflow.

What it does

Technical Debt by Impact, powered by Impact Analyst, is a GitLab Duo Agent Platform flow that runs on merge requests.

When an MR is opened or reviewed, the flow:

• identifies the methods touched by the change
• runs maintainability analysis on those touched methods
• looks for cyclomatic complexity and code smell signals
• mines repository history to find high-churn files
• combines code quality with development impact to produce a simple decision

The result is a traffic-light classification:

• Green: no meaningful maintainability concerns in the touched methods
• Yellow: the MR touches smelly or complex methods, but not in a high-interest hotspot
• Red: the MR touches smelly, complex methods in a file that sits in the top 10% of the repository by commit frequency

This makes the review output immediately actionable. Instead of dumping raw scanner noise into the MR, Impact Analyst tells reviewers when a change is introducing debt in code that will actively slow the team down.

How we built it

We built the project as a GitLab Duo flow with a merge-request-centered trigger and a narrow, explainable automation path.

The flow gathers MR diff context, maps changed hunks to the methods they affect, analyzes those methods for maintainability risk, and then ranks the surrounding files using Git history. That gives us the two dimensions we needed from the research:

• quality: is this code harder to change than it should be?
• relevance: is this code in an area the team changes often?

A lightweight policy engine then turns those signals into the final green, yellow, or red outcome and posts the reasoning back into the MR.

We also kept the flow itself focused by offloading reusable analysis components into an external repository. That let us pull in specialized analysis logic without turning the main flow into a brittle monolith. This approach was explicitly allowed by hackathon guidance, and it made the architecture much cleaner.

We designed installation to be simple and GitLab-native. Teams drop in the flow YAML and trigger the flow. If the required analysis dependencies are already installed, it runs immediately. If they are missing, the system self-heals by opening a new branch and merge request that updates the setup script, explains the dependency, and links to a full technical write-up. In practice, onboarding is close to a one-merge experience: add the flow, review the generated setup MR if needed, merge once, and the review automation is live for future merge requests.

Challenges we ran into

The hardest challenge was avoiding fake precision. Cyclomatic complexity alone is not enough to identify important technical debt, so we had to turn the paper’s hotspot principle into something useful at MR time without overclaiming what the analysis knew.

Another challenge was keeping the workflow explainable. A judge or reviewer should be able to understand why a change is red in a few seconds. That meant we had to keep the classification logic simple enough to trust while still being strong enough to distinguish high-interest debt from low-priority code smells.

We also had to deal with execution reality inside agentic workflows. Parsing touched methods from diffs is harder than scanning entire files. Flow environments are intentionally constrained, so dependency setup had to be automated, auditable, and safe. We did not want a clever demo that only worked on our machine; we wanted a flow that could survive installation friction and still feel easy to adopt.

Accomplishments that we're proud of

We are proud that Technical Debt by Impact translates published maintainability research from an industry leader into a GitLab-native workflow that developers can use immediately.

We are also proud that it focuses on expensive debt, not just ugly code. That is the core product idea. The flow does not try to replace code review with a wall of warnings. It prioritizes the debt most likely to create real drag on delivery.

The setup experience is another accomplishment. Instead of failing when prerequisites are missing, the project turns environment drift into a normal GitLab workflow by opening a setup merge request automatically. That makes the installation path much more realistic for real teams.

Finally, we are proud that the project brings a premium-grade capability into the repository itself. Teams usually expect hotspot-driven maintainability analysis to live in a separate commercial tool. Here, it shows up directly where the decision already happens: in the merge request.

What we learned

We learned that bad code and important technical debt are not the same thing. The most useful signal comes from combining maintainability risk with change frequency. That is what turns static findings into something operationally meaningful.

We also learned that agentic workflows are strongest when they are narrow, disciplined, and deeply embedded in an existing process. GitLab Duo flows do their best work when they feel like focused teammates with a clear job, not like general-purpose chat wrappers.

And we learned that installability is part of product quality. A technically impressive analysis pipeline still loses points if users have to manually debug setup before seeing value. The self-healing setup flow ended up being just as important as the analysis logic itself.

What's next for Technical Debt by Impact

The next step is to expand beyond cyclomatic complexity into a richer maintainability model with more smells, language-aware heuristics, and trend analysis over time.

We also want to move from single-MR triage to longitudinal insight. That means tracking persistent refactoring targets, hotspot trendlines, and maintainability scorecards so teams can see whether their highest-interest debt is improving or getting worse.

Longer term, we see Technical Debt by Impact becoming a maintainability intelligence layer for GitLab. The merge request reviewer is the first step. After that comes organization-level benchmarking, hotspot dashboards, and gamified maintainability feedback inspired by the same research that motivated the project in the first place.

In short: we started by helping reviewers decide whether a merge request introduces high-interest debt. Next, we want to help engineering teams prove that they are reducing it.

Built With

• duo
• gitlab
• gitlab-duo