What to Fix First When Process Visibility Uncovers a Dependency That Was Never Documented

A few weeks into a lean transformation, you pull the value stream map. And there it's: a handoff that lives in someone's head. No standard work. No ticket. No SLA. Just a phone call whenever things get tight. The dependency was never documented—but now it's visible. So what do you fix first?

Who Decides, and By When?

The decision owner is the process owner—not a consultant

When process visibility throws an undocumented dependency into the light, the natural reflex is to escalate. Who should decide what to do? The answer is tighter than most teams expect: the process owner. Not a steering committee, not a visiting Lean coach. The person whose metrics suffer when the dependency fails. I have watched three separate teams waste a full sprint while a manager polled stakeholders for opinions. By the time consensus formed, the customer had already felt the delay. The process owner must own the call because they own the outcome. That sounds harsh until you realize that deferring to a group dilutes accountability—nobody fixes a thing when everybody shares the blame.

The catch is that process owners often hesitate. They lack the habit of deciding alone. But here is the editorial signal worth remembering: an undocumented dependency is already a failure of process discipline. Waiting for permission to patch it only compounds the error. The owner has the data, the context, and the most to lose. They decide.

Time pressure comes from customer lead time or defect rate

How fast must the decision land? Within one sprint or cycle. Maybe faster if the dependency sits on the critical path. The clock doesn't tick because of some arbitrary project governance rule—it ticks because the customer order book or the defect log is the real timepiece. Every day you wait to document and fix the dependency, your lead time stretches or your quality dips. Most teams skip this urgency check. They treat the dependency as a background item, a piece of technical debt that can wait. Wrong order. I have seen a single undisclosed API call from an upstream team turn a five-day delivery into a fourteen-day crawl. No one detected it until the process map showed the handoff gap. The decision window is the sprint cycle because the customer won't wait two cycles for you to decide who owns what.

What usually breaks first is the defect rate. Undocumented dependencies create silent failure modes—the data looks fine until a boundary case hits the undocumented rule. Returns spike. Support tickets multiply. Your process visibility tool just showed you the bomb. The question is whether you defuse it before the next customer shipment. The process owner has maybe ten working days. Not more.

What happens if you defer the fix

Deferring feels safe. You schedule the fix for the next quarter, label it "process hardening," and move on. The odd part is—deferral almost never ends there. The undocumented dependency metastasizes. New team members join and inherit the hidden handoff. They build on top of it. Soon the undocumented behavior becomes accidental architecture. I recall a manufacturing line where a quality check step existed only in one operator's memory. Management knew about it for three months but deferred the documentation. When the operator retired, the defect rate jumped 12% overnight. The decision to defer became a decision to accept risk—without anyone signing off on that risk.

"The cost of deciding later is rarely zero. It compounds in ways the process map can't show until the person who knew the seam leaves."

— line from a plant manager's post-mortem, paraphrased

The alternative? Decide now, even if imperfectly. Lock the dependency into a documented handoff, assign a temporary owner, and schedule a deeper fix within two cycles. That beats the invisible creep. The process owner must ask: does deferring this for one sprint improve customer lead time or reduce defects today? If the answer is no—and it almost always is—then the fix starts now. Not next quarter. Not when the consultant visits again. Now.

Three Options for the Undocumented Dependency

Document first, then fix

The conservative play. You freeze everything—no code changes, no workarounds—and spend cycles writing down exactly what this undocumented dependency does, who owns it, and when it tends to break. I have seen a team do this for a legacy CSV ingestion that three apps pulled from the same S3 bucket. They mapped every field, every cron job, every silent retry policy. It took two sprints. The upside? When they finally fixed the schema collision, they knew exactly why, and the documentation survived three engineer departures. The catch is time. While you write, the dependency keeps failing. Customer tickets pile up. The business asks why you're "writing about the problem instead of solving it." That tension is real—and it often forces a choice between thoroughness and credibility.

What usually breaks first is trust. If you document first but the fix takes too long, stakeholders assume process visibility was a stall tactic. The output is pristine docs. The cost is momentum.

Fix first, then document

Here you patch the broken dependency immediately—maybe a hotfix that reroutes traffic, a new validation layer, or a manual approval gate—and promise to capture the details later. "Later." That's where the trap sits. Most teams never come back to write it down. We fixed this at my previous company by patching an unlisted API call that silently defaulted to an older rate limit. The incident stopped in forty minutes. Nobody wrote a single note. Three months later, the same dependency broke again, and the new on-call engineer had zero context. The fix worked, but the knowledge vanished.

The trade-off is clear: speed now versus memory later. If your dependency is critical to revenue or safety, fix first and assign a specific person (not a team) to document within one week. Set a calendar reminder. Make it a Jira sub-task. Otherwise—and this happens every time—the undocumented becomes the invisible.

“We’ll document it after the release” is the most expensive promise in process improvement.

— engineering director who watched his team rediscover the same dependency three times

Reality check: name the lean owner or stop.

Redesign the process to eliminate the dependency

This is the nuclear option—and sometimes the only honest one. If the undocumented dependency keeps surfacing in different forms, maybe the real problem isn't the missing docs. Maybe the dependency itself shouldn't exist. A team I worked with discovered an internal service that had become a hidden proxy for authentication tokens—it was never listed in any architecture diagram, but every new microservice found it by word of mouth. They could have documented it. They could have fixed it. Instead, they rebuilt the auth flow to remove the proxy entirely. Took six weeks. Hurt for two. After that, the dependency vanished.

But redesign carries its own risk: scope creep. Teams often mistake "eliminate the dependency" for "rewrite the whole system." Set a hard boundary before you start. Ask: If we remove just this one hidden seam, does the customer feel the improvement within one quarter? If yes, go. If no, you might be redesigning for elegance, not for relief. That hurts differently.

Which option fits your pain? That depends entirely on who is waiting—and what they're willing to lose. Wrong order. Not yet. That hurts. Pick one, then move to the comparison criteria.

Comparison Criteria: How to Choose

Impact on Lead Time and Quality

The first lens is brutal but honest: does this undocumented dependency actually delay delivery or degrade what reaches the customer? I have seen teams map a process, discover a hidden handoff to a database team, and then spend three weeks arguing about who should own it—while the customer waited. The catch is that not all undocumented dependencies hurt equally. Some add five minutes to a monthly report; others block a daily deployment pipeline. Measure the cycle time from request to customer-visible result. If the dependency creates a waiting queue that stacks up while people check documentation that doesn't exist, the hit is real. If it only nudges a back-end report by two hours, you might defer the fix. Quality gets trickier—an undocumented external input that can silently corrupt data is a jidoka red flag. That seam needs immediate attention because it violates the principle of stopping the line the moment a defect is detected. A dependency that merely slows things down is a kanban sizing problem. One that injects errors is a process failure. Lead time and quality together tell you whether you're looking at a minor gap or a structural crack.

Ease of Reversal If Wrong

What happens if you choose the wrong fix? Most teams skip this. They pick an option—usually the one that feels fastest—and only realize six weeks later that they built a new process dependency that's even harder to undo than the original silence. The ease-of-reversal criterion asks a simple question: can you walk this back inside two sprints without breaking something else? A temporary manual handoff is cheap to reverse—just stop doing it. Automating a data pull between two undocumented systems? That's expensive to unwind if the schema changes next quarter. The odd part is that teams often over-invest in the permanent solution too early. They build a beautiful integration for a dependency that might vanish in three months when someone finally deletes the legacy spreadsheet. I prefer to ask: "If we're wrong, does our repair cost more than the original problem?" If the answer is yes, pick the reversible path first. That aligns with lean—small experiments, quick feedback, and the humility to pivot before sunk cost drags you into a concrete pit.

'The most dangerous undocumented dependency is the one you try to automate before you understand its volatility.'

— overheard at a kanban retro after a revert that took three full days

Alignment with Lean Principles

Just-in-time and jidoka are not abstract ideals—they're practical filters. A dependency that forces you to stockpile inventory (data, approvals, or batch handoffs) violates just-in-time. If the undocumented step requires you to pre-produce work because you can't pull it on demand, you have created a warehouse of waiting. That's a lean sin. Conversely, a solution that builds a visual signal—like a kanban card that pops up when the dependency activates—preserves flow. The second principle, jidoka, asks: can this dependency fail silently? If the answer is yes, you have no quality safeguard. The correct fix builds an automatic check that stops the process when the undocumented link breaks. A manual approval step might satisfy jidoka if it includes a self-check; a fully automated pipeline that assumes the dependency always exists doesn't. Alignment here often means choosing the messier but more transparent option. A shared spreadsheet that everyone can see is leaner than a perfect API that no one understands until it breaks on a Friday night. That sounds backwards, but I have watched it play out: transparency beats elegance every time when the dependency is undocumented for a reason—usually because someone was afraid to surface it.

Trade-offs at a Glance

Document-first: safe but slow

You freeze work, assign a writer, and wait three sprints for a spec that nobody reads. That sounds harsh—but I have watched teams burn two weeks perfecting a dependency diagram while the customer sat broken. The upside is real: once documented, the seam between systems finally has a single source of truth. New hires won't trip over the same landmine. The catch? Your process visibility just revealed a live wound, and you're applying a bandage that takes days to ship. The dependency continues to misbehave in production while you polish metadata. One product manager I worked with called this "dying of paperwork." He was not wrong.

What usually breaks first is urgency. The undocumented link surfaced because something hurt—a failed deploy, a data mismatch, a midnight alert. Document-first assumes you can decouple discovery from fixing. Sometimes you can. More often, the delay lets the real problem mutate: other teams build on top of the broken assumption, and the documentation effort suddenly traces a moving target. You win clarity but lose tempo.

Fix-first: fast but risky

Patch the code, update the config, deploy in the afternoon—done. I have done this. It feels efficient until the seam blows out six weeks later because the fix addressed a symptom, not the root. The risk is immediate: you hardcode a workaround that becomes the new undocumented standard. Teams downstream see the change, assume it's intentional, and build dependencies on top of your quick fix. Now the original dependency is buried under three layers of implicit trust. The trade-off feels like speed, but the hidden cost is deferred rework—often at double the effort.

However, fix-first wins when the dependency is causing active data corruption or blocking a revenue path. A fragmented sentence: Right call, wrong reasons. The pitfall is skipping the "why." If you fix without understanding the origin of the omission, you repeat the same error in the next system boundary. One team I advised celebrated a two-hour patch. Three months later, the same dependency disappeared again—different code path, identical failure mode. They had never asked why it was missing in the first place.

Redesign: major but heavy

You rip out the undocumented dependency and replace it with an explicit contract—an API, a shared schema, a service boundary. This is the gold standard. And it takes weeks, sometimes months. The odd part is that teams often reach for redesign when a simple fix would hold. Redesign is major precisely because it forces you to ask: should this dependency exist at all? Maybe the real problem is not the missing documentation but the architectural coupling that made the omission invisible until it broke.

The trade-off is sheer gravity. Redesign consumes cycles that could fix three other undocumented links. But when you inherit a system where the seam is rotten—data formats drift, ownership is ambiguous, testing is impossible—redesign pays back every hour. A blockquote fits here:

“Every undocumented dependency is a deferred decision. Redesign forces you to make that decision now, on your terms, not during an incident.”

— senior engineer reflecting on a six-month replatforming project

Honestly — most lean posts skip this.

The heavy version also demands organizational buy-in. You can't redesign a dependency in isolation if it touches three teams and two data stores. The risk is scope creep: what started as one missing link becomes a re-architecture of the entire integration layer. That hurts. But if the dependency is central to your product logic—not a minor config file—the weight of redesign may be lighter than the cumulative cost of twenty quick fixes over two years.

Wrong order: start with redesign when a patch would do, or patch when a documentation gap will keep returning. The choice hinges on one question: how much does this dependency hurt, and who feels the pain first?

Implementation Path After You Pick

Quick wins if you chose document-first

You picked the safe route. Now execute in three working days. Day one: pull the person who actually runs the undocumented process — not their manager — into a 45-minute screen-share. Watch them do the hand-off once, then record a Loom of the steps. Day two: drop that video into a shared doc, annotate every decision point with a timestamp, and flag the one input nobody can find. Day three: circulate the doc to the downstream team. Give them 24 hours to object. No objections? The dependency is now documented. One caveat: this only works if the dependency is simple — a single field, a fixed rule, a known person.

The trap here is false closure. You write it down, you check the box, but nobody reads it. I have seen teams produce beautiful process maps that gather digital dust. To avoid that: pair the documentation with a single automated alert. If the undocumented step is a data transfer, add a webhook that pings the consumer when the file lands. Now the doc has teeth. That usually takes another half-day to wire up.

Pilot if you chose fix-first

Fix-first means you ship a code change or a manual workaround before you fully understand the dependency. Risky? Yes. Sometimes necessary — when the dependency breaks revenue or a live customer SLA. Here is a concrete path: isolate the fix to a single thread or a single account. Don't roll out to everyone. Pick one customer who has already complained about the symptom. Tell them: "We're testing a patch for the issue you reported." Then deploy the fix to just their transactions. Monitor for 48 hours. If nothing breaks, expand to five accounts. Another 48 hours. Then a full release.

The ugly part: you might carry technical debt for months. The workaround bypasses the undocumented step rather than fixing the root cause. That's fine for a quarter, not forever. Set a calendar reminder for 90 days out: "Revisit dependency X — convert workaround to permanent solution or document it." Without that reminder, the fix becomes the permanent state, and the next engineer inherits a mess of tangled exceptions. The odd part is — most teams skip this timer. Then they wonder why their system feels fragile.

Kaizen event if you chose redesign

Redesign is the nuclear option. You're not patching or documenting; you're rebuilding the hand-off itself. That deserves a structured blitz. Block three consecutive days — no meetings, no interrupts. Assemble exactly five people: one person who suffers under the current dependency, one who unknowingly created it, one engineer, one QA, and one neutral facilitator. Day one: walk the entire flow on a whiteboard, from the first trigger to the final consumer. Mark every moment where the dependency eats time or introduces error. Day two: sketch two alternative flows. One can be aspirational (your ideal state), the other must be implementable in two weeks. Day three: pick one, write the step-by-step implementation checklist, and assign owners with deadlines.

What usually breaks first is scope creep. Someone says, "Well, while we're redesigning, let's also fix the reporting." Stop that. The kaizen event has one output: a new, documented dependency that works. Not a new dashboard. Not a new approval process. If you can't finish the redesign in three days, you chose the wrong level of ambition. Cut the scope. Ship something.

“A documented dependency that's ugly but live beats a perfect one that never leaves the whiteboard.”

— remark from a plant-floor supervisor during a lean workshop I facilitated

After the event, let the participant who suffers most lead the implementation. They have the pain, so they have the motivation. Give them a 14-day deadline and daily 15-minute standups. If necessary, pause all other work on that team for those two weeks. Yes, that hurts short-term velocity. But the alternative is another six months of poking at an undocumented tangle that nobody owns. That hurts more.

Risks of Choosing Wrong or Skipping Steps

Document-first can create process debt

You discover an undocumented dependency, and your instinct is to fix the documentation gap before touching the code. That sounds responsible—until the dependency changes twice while your wiki page is still in review. I have watched teams burn three sprints writing up dependencies that were already shifting under their feet. The documentation becomes a frozen snapshot of a moving system, and everyone treats it as truth. Then the next deploy breaks anyway because reality diverged from the spec by lunchtime on day one.

The catch is that document-first feels safe. You get a ticket, you write a page, you pat yourself on the back. But you have created process debt: nobody questions the doc, yet nobody validates it either. The real hazard is not the missing diagram—it's the false confidence that the diagram is correct. One team I worked with spent six hours mapping a Kafka topic's consumers, only to discover that the actual routing was handled by a regex transform buried in a configmap nobody owned. Their doc was beautiful. It was also wrong.

Wrong order. You lose trust in the documentation system itself, and then nobody writes anything. That hurts more than the original gap.

Fix-first can hide the root cause

The opposite trap: you see the undocumented link, you wire it in directly, and you move on. Feels fast. What usually breaks first is the next person who inherits that code—because the dependency is still invisible, just now it works by accident. I have debugged production incidents where the hotfix was correct but the underlying logic was never surfaced. The team shipped the patch, celebrated, and three months later the same seam blew out when a different service changed its payload shape.

Reality check: name the lean owner or stop.

'We patched it so fast that nobody asked why the link was missing in the first place.'

— a lead engineer who had to rewrite the same integration twice

The fix-first path hides the root cause because you never stop to ask: Was this dependency intentionally omitted? Was it a handover mistake? Did the original dev assume a default that no longer holds? You trade a five-minute investigation for a fifty-minute outage later. The odd part is—most teams skip the investigation precisely because they're fast. Speed becomes the excuse for blindness. And blindness repeats.

Redesign can stall without buy-in

This is the grandest failure pattern. Someone sees the undocumented dependency and proposes a full redesign—new interface, new contracts, maybe a whole service boundary shift. That sounds like the grown-up move. But redesign without stakeholder buy-in is a slow-motion derailment. I have seen a perfectly reasonable refactor sit on a backlog for nine months because the team never clarified who would own the new boundary. The dependency stayed undocumented. The system kept limping. Everyone nodded at the redesign doc and nobody shipped it.

What kills the effort is not technical risk—it's the absence of a decision date. Redesigns demand a clear 'who decides and by when' (that's section one of this article for a reason). Without it, the redesign becomes a conversation generator, not a delivery vehicle. The risk is not that you pick the wrong architecture; it's that you never pick any architecture, and the undocumented dependency calcifies into a permanent blind spot. That's worse than either document-first or fix-first, because you spent energy and got zero improvement.

Measure the outcome, not the ambition. If the redesign can't start within two weeks, patch the immediate gap and flag the redesign as a separate, time-boxed experiment. Don't let the perfect become the enemy of the known.

Mini-FAQ: Common Questions

What if the dependency is external—a vendor API, a partner data feed, something we can't control?

Then you have two distinct problems, not one. The undocumented dependency itself is a knowledge gap inside your team. The external link is a reliability risk. I have seen teams spend weeks polishing internal documentation while the external endpoint changed without notice. Fix the contract first. Ask: does your code fail gracefully when that external call times out or returns garbage? If yes, document the dependency after the safety net is in place. If no, stop everything and wrap that external call in a circuit breaker. The documentation can wait an afternoon; a production outage can't. The odd part is—once you add a retry with exponential backoff, the team suddenly remembers to write down where the data comes from.

Should we blame someone for not documenting it?

Sure, if you enjoy meetings that produce nothing actionable. The real question is whether the dependency was knowingly omitted or genuinely invisible until process visibility caught it. Most teams skip this nuance: undocumented doesn't mean malicious. I have seen a senior engineer assume "everyone knows" the CRM webhook feeds the billing table. Nobody knew. The fix isn't blame—it's a lightweight dependency manifest that lives next to the code, not buried in a wiki from 2021. One concrete anecdote: a team I worked with spent two hours in a "lessons learned" postmortem pointing fingers. We restructured that time into mapping the real data flow on a whiteboard. Found three more undocumented links. Blame yields resentment; mapping yields clarity.

How often should we revisit the decision we made about the dependency?

After every deployment that touches the connected systems. That sounds exhausting until you realize most dependency rot happens silently. A team changes a field name on their side, your side still works because the mapping is loose, but the semantic meaning drifts. Nobody catches it until the quarterly report numbers look wrong three months later. Revisit the dependency decision at two specific moments: when the upstream system releases a changelog, and when your team adds a feature that touches the same data path. Batch these checks into a fifteen-minute slot on the last Friday of the sprint. That rhythm catches drift before it becomes a fire. The pitfall is setting a calendar reminder but ignoring it—automate a quick integration test that runs against the real external endpoint, even if it only runs once a week.

"Undocumented dependencies are not technical debt. They're blind spots. Debt you can schedule. Blind spots you only find when you hit them."

— Project manager after a postmortem that revealed three teams shared one unlabeled database table

What if the dependency is between teams that don't share a manager?

That's the most dangerous flavor. Each team optimizes for their own delivery targets, and the undocumented handshake rots because neither side owns the seam. The fix is a shared contract test—not a document, not a Slack thread—a failing test that one team's CI pipeline runs against the other's staging environment. Cross-team dependencies need a single source of truth that fails loudly when it breaks. I've seen this save a release that would have shipped with stale assumptions about authentication token lifespan. The catch is convincing both teams to maintain the test. Start with the team that suffers more when the dependency breaks. Usually that's the consumer side. Write the test yourself, offer to fix it when it fails, and let the provider team see the value before you ask them to co-own it. That works more often than escalation.

Recommendation: Start With What Hurts the Customer

Use the criteria to pick one option — then commit

The previous sections gave you three paths and a comparison grid. That's enough to decide. The mistake I see most often is paralysis: teams re-debate the options for another week because no option feels perfect. The catch is — perfection was never on the table. Undocumented dependencies are, by definition, messy. You're choosing which mess to own. If the dependency blocks a customer login flow for 400 users a day, option A (absorb it into a new service boundary) probably wins. If the dependency is a fragile batch file that runs once a month and nobody touches it, option B (leave it undocumented but flag it with a one-line monitor) costs you one afternoon and zero rework. The criteria table in section 3 gives you a decision rule: score each option against customer impact, maintenance cost, and execution speed. Pick the one that lands highest. Then stop deliberating.

Run a small experiment before committing

You don't need a full pilot. I have fixed these by spending two hours on Monday wiring up a single alert — just one — that fires when the undocumented call happens. The data from that alert told us the dependency ran three times per week, not daily as everyone assumed. That changed which option we chose. One experiment. Three data points. Different answer. The pitfall here is the urge to "do it properly" from day one. Resist that. Instead, instrument the dependency with a lightweight log, or manually trace one production incident end-to-end. See the actual frequency, the actual failure mode, the actual owner (if any). Most teams skip this: they pick an option based on folklore and then discover four weeks later that the dependency was already dying on a server nobody uses. A single afternoon of observation catches that.

Document only what you will maintain

'Documentation that nobody reads is worse than no documentation — it creates a false sense of safety.'

— engineer who spent three months cleaning up a wiki nobody touched

That sounds obvious. But I have walked into shops where the dependency was logged in a Notion page, a Confluence space, a Jira ticket, and a Slack pinned message — all of them slightly wrong. The fix: pick one location, write exactly three things (what calls it, what it needs, what breaks if it fails), and set a calendar reminder to re-check it in 90 days. If you can't stomach that reminder, you don't need the documentation. Wrong order: writing the doc first, then planning the maintenance. The correct order is the reverse. First, decide how you will keep the doc alive — periodic trace, on-call handoff review, or automated integration test — and only then write it. The odd part is, most teams skip this step because it sounds administrative, not technical. It's technical. It's the part that prevents you from rediscovering the same undocumented dependency six months from now with a different name.

What usually breaks first is the customer experience. So start there. Pick an option, run a quick experiment, document only what you can defend. That's not a perfect plan. It's a workable one. And in a system where a hidden dependency just surfaced, workable beats perfect every time.