From Fragmented Code to Navigable Systems
STRATALIS — Part 2 of the Building Stratalis series
The first article established that AI fails on IBM i not because of capability — because of missing context. This article makes that concrete.
The Illusion of Having the Code
Most IBM i shops believe they already have everything AI needs.
After all — the source members exist. The system runs. The business depends on it. So the assumption is: if the AI can read our RPG programs, it should be able to work with them.
That assumption is wrong. Having source members is not the same as having a system the AI can understand.
What AI Actually Needs to See
AI does not read code the way an IBM i developer does. An experienced RPG developer can recognize patterns, recall why a service program was designed a certain way, and fill in missing context from years of working with the system. AI cannot.
It depends entirely on what is visible in the environment: file relationships, structural organization, dependency chains, and context embedded in the codebase itself. Without these, the AI is not reasoning. It is guessing.
Research and industry experience consistently show that lack of context and visibility is the primary reason AI produces incorrect or incomplete code — not model weakness. This is especially pronounced in IBM i environments where so much knowledge lives outside the source.
Fragmented Source vs. Navigable Systems
Most IBM i environments are not structured as systems. They are structured as collections.
RPG programs exist in source members spread across source physical files, grouped by language type rather than by business function. A program in QRPGLESRC has no declared relationship to the service program it calls in a binding directory, or to the physical file it reads, or to the CL procedure that submits it as a batch job. Those relationships exist — but only in the minds of the people who built the system.
A navigable system is fundamentally different. It provides a clear structure of components, defined relationships between them, a way to traverse from one part of the system to another, and a representation of how the system behaves as a whole.
Without navigability, the AI is operating in a fragmented view. It sees individual source members. It cannot see the system those members form.
Why Fragmentation Breaks AI on IBM i
Consider a common IBM i scenario. An RPG program calls multiple service programs, reads and updates several physical files, enforces business rules that were added across multiple releases, and is submitted as a batch job by a CL program that handles error routing.
In a fragmented environment, those relationships are not visible to AI. The service program bindings are not in the source. The file dependencies are not declared. The batch job relationship is in the CL — a separate source member the AI has not seen. When AI generates or modifies code in this context, it assumes isolation, ignores dependencies, and produces output that looks correct in isolation — but breaks when it meets the actual system.
This is exactly why IBM i teams experience subtle bugs, incorrect assumptions about data structures, and increased debugging time after AI-assisted changes. The AI did not fail because it was wrong about the code it could see. It failed because it could not see enough of the system.
The Missing Layer: System Structure
The real gap is not tooling. It is structure.
IBM i systems were not designed to expose dependency graphs or execution flow in a form that tools can consume. Object-based organization — programs, service programs, data queues, physical files all living as objects in libraries — made sense for the platform's operational model. It does not provide the structural visibility that AI depends on.
This is also why IBM i modernization efforts struggle in general, not just with AI. Large IBM i environments often lack central visibility into what calls what, which jobs depend on which files, and how changes ripple across the system. AI simply makes that structural gap more obvious and more costly.
What 'Navigable' Actually Means for IBM i
A navigable IBM i system is not just RPG source in files. It is a system where four properties hold.
1. Relationships are explicit. Which programs call which service programs. Which jobs depend on which files. Which modules bind together. These connections are declared in the repository structure, not inferred from object libraries at runtime.
2. Structure reflects the system. Source organization mirrors the business architecture, not the language type. RPG programs, CL procedures, and service programs that serve the same business function live together — not scattered across QRPGLESRC and QCLSRC with no visible relationship.
3. Flow can be traced. You can follow a business transaction from the CL job that submits it through the RPG programs that process it to the physical files it updates — without asking the developer who wrote it twenty years ago.
4. Context is accessible. Business rules are discoverable. The logic encoded in RPG indicators, nested conditions, and multi-program chains is documented in a form a tool can read — not just a person who already knows the answer.
These four properties are what allow AI to understand, reason, and generate meaningful RPG output. Remove any one of them and the AI's output degrades accordingly.
Why This Matters Before AI
This is not just an AI problem. Even without AI, fragmented IBM i systems create real operational costs: new developers take months to become productive, changes to core RPG programs carry significant risk, critical knowledge lives with a shrinking group of experienced staff, and debugging cross-program issues is slow and expensive.
AI does not introduce this problem. It exposes it.
Most IBM i teams approach AI adoption like this: bring AI into the existing environment. The more effective approach is the reverse: make the environment understandable first, then apply AI. That shift changes everything about what AI can deliver.
A Practical Starting Point
You do not need to transform the entire IBM i estate at once. Start with one business system or module.
Focus on making relationships visible, organizing RPG and CL source into a coherent structure that reflects business function rather than language type, and documenting key flows. Even partial structure improves AI outcomes significantly. AI performance improves not with better prompts — but with better systems.
Once systems become navigable, AI can follow logic across programs and service programs, code generation becomes context-aware, refactoring becomes safer, and documentation becomes meaningful. This is where AI starts delivering real value on IBM i. Not before.
Final Thought
AI does not need perfect IBM i systems. But it does need IBM i systems it can see.
Fragmented source members limit AI. Navigable IBM i systems unlock it.
Next in this series: Making Business Logic Machine-Readable — Even with structure in place, one problem remains: the RPG logic is still hidden. The next article covers how to surface it.