Key Takeaways:
- Technical debt on IBM i sits in five specific, measurable ledgers.
- Retiring RPG specialists make undocumented knowledge the biggest risk.
- Measure debt in numbers that finance accepts before funding any single fix.
- Reduce debt as a reversible progression, and not as one vendor’s pitch.
- Cutting technical debt does not require leaving the IBM i platform.
- New screens count as repayment only when they pass three measured tests.
Why do most IBM i modernization projects stall before delivering real business value? The issue is rarely the technology itself. Instead, it is decades of unaddressed structural work that teams have not named clearly enough to fix. That is IBM i modernization technical debt, and on this platform, it goes much deeper than just having old code.
The cost of leaving it unnamed is no longer theoretical. In November 2025, the IBM Institute for Business Value1 reported that 81% of executives say technical debt is already constraining their AI success. For estates that run core operations on RPG and DB2 for i, that constraint looks familiar: integrations that take months, changes that only one developer dares to make, and AI initiatives that cannot reach the data they need.
This guide makes the debt specific, measurable, and payable. It breaks IBM i debt into five ledgers and shows how to measure each one in terms a finance team will trust. It also lays out a reversible reduction playbook that applies fixes only when the data supports them.
Our focus here stays practical and specific. Program-level strategy, platform options, and the full modernization journey live in Damco’s guide to transforming IBM i. This playbook gives you the hands-on debt discipline required to support that work.
What Does Technical Debt Mean on IBM i?
Technical debt on IBM i is the accumulated cost of deferred structural work across code, data, architecture, infrastructure, and knowledge. It is measured as the effort required to fix those gaps. Looking at debt this way turns a vague problem into a clear number. Debt has nothing to do with how old your code is. It is the extra effort every future update requires because structural improvements were postponed earlier.
Ward Cunningham, who introduced the debt metaphor in a 1992 experience report, described the mechanism in a single line that still holds:
“Every minute spent on not-quite-right code counts as interest on that debt.”
Two correctives keep that idea productive on IBM i. First, debt does not mean an application is outdated or badly designed. Many systems with heavy debt were well designed for the business they served. The debt was simply built up as business needs changed. Second, the platform itself is not a problem. The trouble lies in the code sitting on IBM i.
Those correctives let an RPG team read a debt assessment as an engineering plan rather than a verdict on their work. They also support the most important promise in this guide: learning how to reduce technical debt in IBM i does not require leaving IBM i. Every stage of the playbook below can run in place, on the platform your business trusts. Before you fix anything, however, you need a clear map of where that debt sits.
The Platform Was Never the Problem. Here Is Why IBM i Only Looks Legacy
What Are the Five Ledgers of IBM i Technical Debt?
IBM i modernization technical debt falls into five ledgers, each with its own warning signs and costs. This model builds on a four-part framework of code, architecture, infrastructure, and knowledge used in dependency-first analyses of RPG debt. We add data as a separate ledger because, on IBM i, database issues often carry the heaviest weight.
1. The Code Ledger
The code ledger includes fixed-format RPG, monolithic programs spanning thousands of lines, spaghetti CL, and dead or duplicated logic that stays in place because no one is sure if it is safe to delete. This debt can be spotted through long change estimates and hesitation among developers to touch certain files. The business cost is simple: updates take longer and depend on a shrinking pool of developers who can still read the code easily.
2. The Data Ledger
The data ledger covers program-described files, DDS schemas where SQL DDL belongs, and business rules embedded in RPG instead of in DB2 for i constraints, triggers, and views. Its clearest warning sign is a database that cannot explain itself, because field definitions, table relationships, and validations live in application code. As a result, every new tool that needs that data, from reporting dashboards to AI models, must reverse-engineer the programs before it can trust a single field.
3. The Architecture Ledger
The architecture ledger holds point-to-point integrations built up over decades, monoliths where ILE service programs should sit, and business logic coupled to 5250 screens. Integration specialists point to fragile file-transfer jobs, one-off custom interfaces for every partner, and minor edits that trigger unexpected errors across connected apps. When this ledger is full, connecting IBM i to any modern tool turns into a major project instead of a routine setup.
4. The Infrastructure Ledger
The infrastructure ledger holds skipped OS upgrades, outdated PTF patch levels, and aging server hardware. With IBM i 7.6 and Power11 released in 2025, companies running several versions behind miss security updates and face steeper upgrade paths each year. Hardware and OS currency deserves its own dedicated planning track. This ledger seldom causes daily friction, but its risk compounds quietly.
5. The Knowledge Ledger
The knowledge ledger creates the most urgent pressure on IBM i because of workforce demographics. It holds business rules that live in developers’ minds rather than in documentation. Dependency-first analysts measure this single-person risk using a bus factor, which counts how many people would need to leave before a system becomes unmaintainable.
Fortra’s 2026 IBM i Marketplace Survey2 found that 69% of respondents rank IBM i skills as a top concern, marking the first time skills passed cybersecurity at number one. When you score this risk area by area, staffing worries turn into concrete debt with an expiration date.
Naming these five ledgers turns broad anxiety into an assessment. Measuring them turns that assessment into a budget your leadership can approve.
How Do You Measure Technical Debt in IBM i Applications?
Measurement is what separates a debt program from a renovation. But a lot of IBM i guides skip this step. Taking three specific measurements in order gives you a complete view of your environment.
I. Build the Object-Level Inventory and Dependency Map
Begin by cataloging everything running on your system: every program, service program, database file, and CL job. Map how they interact by tracking which programs call one another, which files feed which processes, and where code changes cluster.
Dependency-first practitioners emphasize building this map first because high-activity hotspots show where debt costs the most. Automated analysis tools in the X-Analysis and ARCAD Observer class can handle much of this work, and choosing the right class of tool matters far more than the brand.
II. Calculate the Technical Debt Ratio
Next, express code and data debt as a ratio. The technical debt ratio, formalized in Jean-Louis Letouzey’s SQALE method, divides the estimated effort required to fix the code by the effort it took to develop it. A low ratio points to targeted cleanup work. A high ratio signals the need for deeper structural fixes. Tracking this ratio alongside code complexity and change-failure rates tells how your software behaves during updates.
III. Run the Knowledge Audit
No scanner can read about a retiring developer’s mind, so the third measurement happens through interviews. Hold focused review sessions for each business area to document who understands which rules, assign a bus-factor score to every domain, and compare existing documentation against the logic running in production. This audit creates a ranked list of knowledge risks, each with an owner’s name and, in many cases, a retirement date.
IV. Translate the Numbers Into a Business Case
These measurements give finance teams a concrete reason to approve funding. In a February 2026 analysis of brownfield modernization, IBM3 reported that organizations overlooking technical debt risk losing 18% to 29% of expected returns. The same report stresses that debt reduction belongs inside modernization delivery rather than in a separate cleanup project. The scale of the problem explains the urgency: CAST’s 2025 global study4 of more than 10 billion lines of code put accumulated debt at 61 billion workdays of repair effort.
The takeaway for any IBM i budget review is simple. A debt program without hard measurements looks like an open-ended renovation, while one backed by clear numbers wins funding.
Want these numbers for your own estate? Ask Damco to run an IBM i modernization assessment across all five ledgers, so the measurements come before any recommendation.
What Is the Right Sequence for Reducing IBM i Technical Debt?
Knowing how to reduce technical debt in IBM i comes down to sequence. Most vendors sell a single remedy. One pushes free-format conversion. Another sells database migration or an API toolkit. Each option can help, but none solves everything on its own. A better approach treats these steps as a sequence, with every stage triggered by the ledger evidence gathered during measurement.
Stage 1: Analysis Before Any Remedy
Do not skip analysis. The inventory, ratios, and knowledge audit from the previous section serve as your entry ticket for every stage that follows. In their absence, teams usually fix easy programs rather than the ones that cost the most. They also cannot prove later that conditions have improved.
Stage 2: Free-Format Conversion Where the Code Ledger Dominates
Start here when the code ledger dominates. Moving fixed-format RPG to free-format makes code easier to read. It also helps more developers maintain the system. Supporters of free-format conversion make a clear point: every converted program reduces reliance on a shrinking specialist group. That said, conversion only changes syntax. A converted monolith still remains a monolith.
Stage 3: Database Modernization Where the Data Ledger Dominates
Focus here when data debt leads. Move DDS definitions to SQL DDL. Shift embedded validation and relationship rules into DB2 for i constraints, triggers, and views. Some database specialists report cutting RPG codebases by roughly 80% through this shift alone. Treat that figure as their reported result and not a benchmark. Real savings depend on how much database logic sits inside your programs.
Stage 4: Modularization and API Enablement
Turn to this stage when architecture debt creates bottlenecks. Break monoliths into ILE service programs. Expose proven RPG logic through APIs. Specialists call this pattern wrapping rather than rewriting. Web, mobile, and partner apps can reuse trusted business rules without rebuilding them from scratch. That lowers the risk of losing hard-won logic.
Stage 5: Selective Re-Engineering Where the Ledgers Prove It
Save re-engineering for last, and keep it small. Use it only where ledger data shows rebuilding costs less than fixing the existing code. Even then, pick the smallest slice the evidence supports. Leave everything else in place, so that it keeps generating value.
Two Principles That Govern Every Stage
Every stage must keep the system running and the program reversible. Just as important, none of it requires leaving IBM i.
AI tools can speed up parts of this work. As of November 2026, IBM’s Bob coding assistant, available since March 2026 and the successor to Watsonx Code Assistant for i, can explain RPG, assist with fixed-format to free-format conversion, write documentation, and generate tests. Even so, AI cannot replace good sequencing decisions. Damco covers this balance in more detail in its guide on how AI helps in modernizing IBM i.
Which Practices Keep IBM i Technical Debt from Coming Back?
Paying down debt solves only part of the problem. Daily habits must stop new debt from piling up behind your changes. Damco’s enterprise guide frames modernization as an ongoing journey. Debt reduction works the same way. It is a steady habit, not a one-time cleanup. Experienced IBM i teams rely on several core practices:
- Version control with Git: Move RPG, CL, and DDS source code out of source physical files and into Git. With this step, teams gain branching, full history, and safer parallel work. It also sets the base for later engineering practices.
- CI/CD pipelines and automated testing: Run automated builds and regression tests around high-risk hotspots to make each change repeatable and catch breakage before it reaches production. This safety net makes developers willing to touch the fragile programs that carry heavy debt.
- Modern development environments: Use RDi tools and VS Code extensions for IBM i to add code outlines, refactoring aids, and inline documentation to RPG work. They make free-format code faster to edit, and they shorten onboarding for new developers.
- Documentation as a deliverable: Update documentation of the affected business rules with every code change, so the knowledge ledger is repaid in small installments. This habit costs far less than a documentation sprint launched in a panic right before a key developer retires.
- Structured knowledge transfer: Use pair programming, recorded walkthroughs, and rule extraction into docs and tests. This way, retiring experts pass what they know into assets the business owns. Tied to retirement dates, this becomes planned engineering work rather than a last-minute HR task.
That last practice deserves a real budget line. Knowledge transfer is debt repayment with a deadline.
Does Modernizing the Interface Reduce Technical Debt?
Not on its own. Modern interfaces do not automatically reduce technical debt. Often, teams mistake surface updates for debt payoff. Three common patterns show why:
- Screen refacing sold as modernization: Browser screens layered over 5250 programs can genuinely improve the user experience. But the programs, files, and integrations behind those screens stay as they were. As a result, technical debt behind them remains unchanged when the new interface goes live.
- A portal on top of an untouched monolith: Customer or partner portals can open new sales or service channels. If they call tangled legacy programs, they add another connection to the architecture ledger. And that can make future changes harder, not easier.
- A conversion with no restructuring: Converting fixed-format RPG to free-format without breaking up monoliths or moving database logic improves readability. It is a worthwhile first step, though complexity, coupling, and bus factor can remain where they were before the project began.
Three Tests That Separate Repayment from Theater
Teams can mistake surface updates for debt payoff, a kind of modernization theater. To ensure this doesn’t happen, check every initiative against three before-and-after questions:
- Did measured complexity drop?
- Did bus factors improve in the affected areas?
- Did change lead time fall for the programs involved?
If the answer to all three is no, the project may still have value. It just did not pay down technical debt.
Theater is not worthless; it is just not repayment. Calling it repayment hurts budgets when future change estimates stay just as slow.
Here’s Why IBM i Green Screens Cost You More Than You Think
How Should a Debt-First Sequence Feed the IBM i Modernization Roadmap?
Once your checks are ready, the work needs a steady pace. A debt-first sequence works best as a repeatable rhythm rather than a rigid calendar. It rests on three parts:
I. The Starting Quarter
Spend the first 90 days mapping dependencies. Then add tests, automation, and documentation around hotspots the map reveals. Hold off on conversions or re-architecture until those guardrails exist. Early work stays at a lower risk and teaches you more.
II. The Quarterly Rhythm
After the first quarter, run one ledger-driven item per cycle. Measure debt ratio, bus factor, and lead time before and after each step. Show clear wins, so finance sees compounding returns instead of taking them on faith.
III. The Sequencing Rules
Three rules set the order. First, knowledge-debt items tied to upcoming retirements jump to the front. A rule lost with its only owner cannot be recovered later. Second, keep every step reversible so nothing locks your estate into a dead end. Third, the report measured results before funding the next step.
This sequence does not replace broader planning. It feeds the modernization roadmap that covers program-level priorities, platform choices, and the long-term journey.
How Does Damco Help Reduce IBM i Technical Debt?
Damco’s work on the platform goes back to its AS400 roots. Its teams bring over three decades of enterprise modernization experience and more than a million hours in IBM i projects. That background fits the careful work that debt reduction requires.
At Damco, every IBM i modernization project starts with a ledger-based assessment before any fix is proposed. Teams set baseline metrics before and after each step, follow a reversible sequence, and build knowledge transfer into delivery from day one. Engineers work on RPG, CL, DDS, and DB2 for i in place, while Damco’s IBM i support services keep daily operations steady.
Because measurement comes first, Damco treats IBM i modernization technical debt as a portfolio to be ranked, not a backlog to be cleared. Recommendations change when the numbers do. Some estates need free-format conversion first, others need database cleanup, and many need knowledge capture right away. If your wider business also carries debt outside IBM i, Damco’s legacy modernization services use the same evidence-first approach.
Talk to Damco about a debt-first modernization sequence for your estate, with the enterprise guide as your strategy companion along the way.
References:
- 1. IBM Institute for Business Value
- 2. Fortra
- 3. IBM
- 4. CAST
Frequently Asked Questions
Technical debt in IBM i is the accumulated cost of deferred structural work, measured as the effort needed to fix it. It sits in five ledgers: code, data, architecture, infrastructure, and knowledge. Fixed-format RPG, DDS schemas, point-to-point integrations, lagging OS releases, and undocumented business rules held by retiring developers are typical examples.
Measure it in three steps. Build an object-level inventory and dependency map to find hotspots. Calculate the technical debt ratio using the SQALE method, comparing remediation effort with development effort. Then run a knowledge audit through interviews, scoring each business domain for bus factor and documentation coverage, so finance sees real numbers.
Learning how to reduce technical debt in IBM i starts with analysis, not a remedy. Measure the five ledgers, then apply free-format conversion, database modernization, and API enablement only where the evidence calls for each. Reserve re-engineering for proven cases, keep every stage reversible, and do it all in place on the platform.
No. The platform is rarely the problem; the debt lives in the code, data, integrations, and knowledge running on it. Free-format conversion, DDS to SQL DDL migration, service programs, and API wrapping all happen on IBM i itself. They preserve decades of proven business logic instead of rewriting it from scratch at great risk.
It depends on estate size, ledger severity, and team capacity, so no honest figure fits every estate. A common pattern begins with a focused 90-day quarter of dependency mapping, testing, and documentation around hotspots. After that, one measured initiative per quarter makes debt reduction an ongoing capability rather than a single project.





