Executive Summary
An action-taking agent pilot tests more than AI.
It exposes weaknesses in the underlying architecture, from unclear rules and brittle interfaces to incomplete data and hidden exceptions. When a pilot stalls, the problem may not be the model but the systems around it. This article explains how to tell the difference, identify the six types of architecture debt, and decide where to fix them.
Key Takeaways
- Users often compensate for unclear rules and missing information. Agents expose these gaps because they cannot rely on human judgment or workarounds.
- Reproduce a failure outside the model before diagnosing it. Only problems that persist should go on the modernization backlog.
- Six types of architecture debt commonly emerge: logic, contract, authority, data, state and transaction, and evidence debt.
- Adapters are useful when they translate between systems. They become debt when they take on business rules, access decisions, or workflow state.
- Three gaps should block production: unclear permissions, unrecoverable progress, and unverifiable outcomes.
- A stalled pilot should produce a focused modernization backlog for one workflow, not trigger a complete rewrite.
The usual response to a stalled agent pilot is to blame the model and rewrite the prompts. This article tests that reflex against one fictional but familiar case: an embedded offboarding agent in a B2B work-management product. It shows how to separate an agent failure from an architecture failure, reads a single trace that does exactly that, names the six debts such traces reveal, and ends with the smallest backlog that gets the workflow moving again. Start with what the debt actually is.
What Is Architecture Debt?
Architecture debt is the gap between what a product’s structure can express and what its workflows need. It builds up from decisions that worked while a person was in the loop: a rule enforced only by a screen, a permission model with no narrow roles, two systems that both own the same record, a multistep job tracked in someone’s head, and an operation whose success nobody verifies.
It differs from code-level technical debt in where it lives. The team that owns a service can refactor messy code inside it. Architecture debt sits between services, data sources, and permission models, so paying it down usually takes decisions across teams.
While people do the work, the debt costs little, because people route around it. It starts charging interest when software has to act on its own, which is why an action-taking agent pilot exposes it.
Understanding Architecture Debt with an Example
Picture the pilot in use in an HRMS platform. An authorized administrator asks the offboarding agent to offboard a departing employee, a job with seven steps:
- Confirm the person and the effective date.
- Revoke active sessions.
- Disable application access.
- Transfer owned projects and files.
- Reassign open approvals.
- Preserve required records.
- Log completion, with any unresolved exceptions.
The model understands the request on the first try. The pilot stalls anyway.
The team reads that as a model-quality problem and starts tuning prompts. The blockers can sit lower. Some rules exist only in the interface. Permissions are too broad to delegate. HR, the directory, and the product itself disagree about who owns what. APIs cannot say whether a job finished, and nothing reliably proves that any step completed. Each is a form of architecture debt, and each stays invisible while someone does the work.
Experienced Users Can Innately Navigate to Find Workarounds
Experienced users know which screen shows the real status, which validation message is safe to ignore, which operations must run in order, and which exceptions get handled outside the product entirely. None of that lives anywhere an agent can reach.
The point is not that people are dependable and agents are fragile. People compensate for missing rules, inconsistent states, and ambiguous errors without noticing. That compensation is the debt’s camouflage. Take the person out of one workflow, and the camouflage goes with them. So when the pilot stalls, the first job is to establish whether the agent failed or the product did.
How Do You Test Whether a Failure Belongs to the Architecture Instead of the Pilot?
Repetition localizes a problem. It does not prove the cause. A pilot can break at the same handoff on every run because of tool schemas, prompt design, or the model itself. Before a failure earns a place on the modernization backlog, isolate it in four steps:
- Confirm the action. Check that the model interpreted the request and selected the intended operation.
- Replay without the model. Run the same operation with fixed inputs through a deterministic client: a scripted caller that sends identical inputs every time, with no model in the loop.
- Inspect the operation. Review its contract, the authorization it ran under, the operational state, and the trace.
- Classify the result. If the operation still fails, classify the architecture debt. If it succeeds, investigate the agent, the prompts, or the tool design instead.
Replay is strong evidence, but it has limits. A passing replay clears the operation under the inputs you used, not under every condition. When a failure depends on timing, concurrency, or the state the system was in when the agent called it, replay against that state before you clear the product. A failing replay can also reflect a different environment or credential, so confirm that the replay matches the conditions the agent ran under.
A repeated failure at one handoff is a clue, not proof. In the modernization assessments I run, the recurring version of this is a team two weeks into prompt tuning when the blocker was a permission model all along. Here is what the method looks like on one step of the offboarding job.
Exposing Contract Debt and Evidence Debt
Take step 2 of the offboarding job, a revocation that reported success while two sessions stayed active, and read its trace field by field.
Trace: offboarding step 2, session revocation
- Expected action
- Revoke all active sessions for the departing employee.
- Actual result
- The agent calls the revocation operation and gets a success response.
- Manual check
- Two sessions remain active on an older single sign-on system.
- Replay
- Repeating the operation outside the agent produces the same result, confirming a product defect.
- Diagnosis
- Contract debt: The operation covers only the primary identity provider.
- Evidence debt: The platform cannot check sessions across both providers.
- Disposition
- Add session inventory and verification to the core platform. Use an adapter to revoke sessions across both providers until the core fix is ready.
One trace, and the pilot has produced a diagnosis, an owner, and two backlog items. The rest of this article generalizes that reading, starting with the six debts a replay can surface.
A success response proves what the endpoint promised. It doesn’t prove the business outcome happened.
Six Architecture Debts an Action-Taking Agent Exposes
We use six categories to read recurring failures in action-taking agent pilots. Each one below starts with how the offboarding agent meets it, then points to the smallest lasting fix.
Logic Debt: Rules That Exist Only in the Interface
The offboarding agent has to decide which accounts a departing contractor keeps. If that rule must be reverse-engineered from screens, or duplicated into the agent’s prompt, the rule does not exist as far as the product is concerned.
Business logic and interface behavior are different things, and the difference becomes expensive the day software has to act. The fix is extraction: stable rules move into deterministic services or policy that the product itself enforces.
Contract Debt: Operations That Cannot Say Whether the Job Finished
The offboarding agent calls an operation and gets back an answer that cannot tell it whether the job finished, why it failed, or whether a retry is safe. The debt is what the contract leaves out:
- Declared preconditions.
- Stable schemas.
- Errors that state a cause.
- An answer to whether the job finished.
- Defined retry and recovery behavior.
Contract debt is not shorthand for bad APIs. Resource-oriented interfaces, which expose data objects such as users and files rather than whole business tasks, are not the villain. Well-specified resource operations compose into workflows.
Goal-shaped operations, which perform one complete business task such as “offboard this user,” make an agent’s tooling simpler and are worth having. The requirement, though, is the dependable contract.
Authority Debt: Permissions Too Broad to Delegate
A powerful backend credential plus prompt instructions saying “only touch this tenant” is not least privilege; it is trust in a sentence. The agent needs authority bounded to the tenant, the user, the workflow, the action, and the resources involved.
Where the permission model cannot express that boundary, the pilot has found a security backlog item that predates the agent.
Data Debt: Systems That Disagree About Who Owns What
Missing data is the easy version. The harder version is conflict: HR says the employee left Friday, the directory says active, and two systems both claim to own project assignments. An agent cannot arbitrate ownership that the system landscape never settled. The remedy is authoritative sources and reconciliation rules, decided once and encoded.
State and Transaction Debt: Workflows That Cannot Survive Partial Completion
Offboarding is not one atomic write. It is a sequence in which partial completion is normal. The workflow must represent what completed, what failed, what can be retried, and what needs a person. It must also survive a mid-workflow restart.
Agent memory and conversation history are not workflow state. Durable progress and recovery state belong in the business workflow or the system of record.
Patterns for long-running sequences already exist. The saga pattern, for example, breaks a long transaction into steps and pairs each step with a compensating action that undoes it if a later step fails. The debt is that the workflow was never modeled as a single unit.
Evidence Debt: Outcomes Nobody Can Prove
When security asks which sessions were revoked and when, the product needs an answer stronger than a log line showing that a call returned 200, the HTTP status code for success. Evidence debt is the gap between what happened and what you can prove.
A successful response proves what that endpoint’s contract promises. In a workflow that spans systems, it does not prove the business outcome. Two mechanisms close the gap, and they do different jobs:
- Durable event history provides attribution and sequence: who did what, and in what order.
- An end-state check confirms the outcome: the sessions are actually gone.
The product needs both. Evidence debt is the quietest of the six, and the first one compliance will find.
How to Tell Neighboring Debts Apart
Three pairs are easy to confuse, and confusing them sends the fix to the wrong place.
Contract versus evidence. Contract debt concerns what an operation promises. Evidence debt concerns whether anyone can independently check the outcome. The session-revocation trace showed both at one operation.
Logic versus authority. Logic debt means the product does not encode the rule. Authority debt means the product cannot restrict who may carry out an operation, even when the rule is clear.
Data versus state and transaction. Data debt means systems disagree about the facts. State and transaction debt means the workflow cannot track or recover its own progress.
Symptom-to-Debt Reading Key
The table maps symptoms to hypotheses, not verdicts. Every row assumes the replay has already cleared the agent.
| Pilot symptom | What to investigate | First remediation direction |
|---|---|---|
| Every exception spawns a new prompt rule | Logic debt | Move stable rules into deterministic services or policy. |
| The agent chooses between overlapping operations inconsistently | Contract debt | Consolidate around distinct, goal-shaped capabilities. |
| The pilot only works with a highly privileged credential | Authority debt | Introduce resource- and transaction-specific permissions. |
| The agent keeps asking for information it should have | Data debt, or a retrieval gap rather than architecture debt | Define authoritative sources and retrieval contracts. |
| A retry creates duplicates or inconsistent state | State and transaction debt | Add operation records, idempotency (a retried call produces the same result, not a duplicate), and recovery semantics. |
| The agent reports done, and nobody can confirm it | Evidence debt | Define end-state checks and completion evidence. |
Naming the debt is half the diagnosis. The other half decides what the fix will cost.
How Do You Decide Whether a Fix Belongs in an Adapter or the Product?
Once you have a diagnosis, one decision drives cost and honesty: where the fix lives.
When an Adapter Is Permanent Architecture and When It Becomes Debt
An adapter earns its keep when the underlying behavior is stable and correct, and the gap is naming, schema translation, or aggregating a few calls into one operation. An adapter that only translates stable behavior may be the permanent answer. Governed façades (controlled interfaces placed in front of existing systems) and anti-corruption layers (translation layers that stop one system’s model from leaking into another) are recognized architecture, not scaffolding.
An adapter becomes debt when it quietly acquires duplicated rules, authorization decisions, or workflow state without clear ownership. Every further adapter will rebuild them, and the copies will disagree. When the gap is rules, authority, or workflow state, the adapter defers the modernization invoice. It does not cancel it.
When the Product Itself Must Change
Change the product itself when any of these conditions hold:
- The same problem blocks several workflows.
- Business rules exist only in the UI or the prompt.
- Permissions cannot be narrowed safely.
- Multiple systems claim the same state.
- Partial completion cannot be represented.
- Compliance and support need authoritative evidence.
Three Gaps That Should Block Production
Three kinds of gaps should block production: authority that cannot be narrowed to the workflow, state that cannot be represented or recovered after partial completion, and outcomes that cannot be verified independently. Ship past those and the agent operates with too much power, unknown progress, and unprovable results. Naming gaps, schema translation, and tool ergonomics are fixable behind an adapter and should not block.
That sorting tells you what is urgent. The backlog tells you what order to do it in.
RECOMMENDED READING
How Do You Build the Minimum Viable Modernization Backlog?
Modernizing the whole product before continuing the pilot is the wrong conclusion in the other direction. Prioritize what the specific workflow requires, in the order the workflow needs it.
Remediate in Workflow Order
Each step closes one of the six debts:
- Establish the authoritative state and the success condition (data debt). This step also defines what “done” means, which the final step proves.
- Define the narrow authority the workflow requires (authority debt).
- Extract the business rules the workflow depends on (logic debt).
- Repair or wrap the product contracts involved (contract debt).
- Add persistent workflow and recovery state (state and transaction debt).
- Capture verification and audit evidence (evidence debt).
Missing event history belongs on the backlog with special urgency. Without it, the team can confirm the end state but cannot attribute how the system got there.
Classify Every Fix by Where It Lives
Then give each remediation one of five dispositions:
| Disposition | What it means |
|---|---|
| Pilot-specific adapter | A translation or aggregation layer that serves this pilot, such as the interim revocation adapter. |
| Shared platform capability | A fix that several workflows or agents will reuse. |
| Core product change | A gap in rules, authority, state, or evidence that the product itself must own. |
| Deferred limitation | A known gap the workflow operates around for now, documented rather than hidden. |
| Unexposed capability | An operation the agent should not reach until its debt is resolved. |
The final disposition also feeds the ‘Agent Access Matrix’, the framework that separately determines whether and how each capability should be exposed to agents (see our upcoming article for more).
Why Is a Stalled Pilot a Diagnostic Report on the Product?
A failure that survives a deterministic replay is the pilot returning results. It shows where the product and the systems around it cannot yet express rules, authority, state, and outcomes clearly enough for software to act on them.
The pilot failed as a demonstration and succeeded as a diagnostic. Teams that treat it that way come out with a focused backlog and a stronger product. Teams that keep tuning the prompt end up with a better-worded version of the same stall.
FAQs
Reproduce the failing operation outside the model. Replay it with fixed inputs through a deterministic client, then inspect the contract, authorization, operational state, and trace. If the operation still fails, the debt is most likely architectural. If it passes, investigate the agent, the prompts, or the tool design, unless the failure depends on timing or system state.
No. MCP (Model Context Protocol) standardizes how tools and systems are exposed to agents, and good schemas remove one source of confusion. Neither can create business rules, authorization boundaries, workflow state, or outcome semantics the product does not have. A standard interface to a product that cannot express its own rules is a cleaner view of the same debt.
Three kinds: authority that cannot be narrowed, progress that cannot be recovered after partial completion, and outcomes that cannot be verified. In the session-revocation trace, the evidence gap blocks, because nobody can prove the sessions are gone. The contract gap does not, because an adapter can aggregate the two revocation calls while the core fix ships.
Did your agent pilot expose more than an AI problem?
We help product teams turn pilot findings into a focused modernization backlog across APIs, permissions, workflow state, data ownership, and operational evidence.