When Editing Legacy Docs Creates Debt for the Next Custodian

You inherit a doc set. Maybe it's a knowledge base from a team that disbanded, a README with three years of stale PRs, or internal wiki pages nobody touches. The easy thing is to start rewriting—fix the grammar, consolidate the orphans, add a missing screenshot. But every edit carries a hidden cost. The next person after you won't know what you removed, why you changed the tone, or which parts you were afraid to touch. That's the ethical debt: choices that make the next custodian's job harder, not easier.

This isn't about perfection. It's about realizing that your edits today are someone else's legacy tomorrow. Over the next eight sections, we'll look at where this shows up in real work, what editors confuse with good practice, patterns that actually hold up, and the anti-patterns that teams keep repeating. If you've ever fixed a doc and felt a twinge of guilt, this one's for you.

Where This Shows Up in Real Work

Inherited support docs with no owner

You open a ticket about a config file that won't parse. The answer should be in the internal knowledge base—but what you find is a page last touched eighteen months ago by someone whose Slack avatar is now a generic grey silhouette. The doc says "contact the platform team." There is no platform team. Reorg scattered them three quarters back. One paragraph still references a Jira project that was archived for 'deprecated' status last spring. The code sample shows a flag that doesn't exist in production. You spend forty minutes tracing who wrote it, then another hour cross-referencing git blame against Slack history to guess what the flag actually became. The ticket itself takes four minutes to resolve. That hour of archaeology? That's the debt—capitalized at interest, compounded by every future reader who hits the same dead link.

The catch is that nobody set out to create bad documentation. The original author was thorough, even helpful—they just moved teams before the next migration. No handoff. No expiry date stamped on the page. So the doc sits, looking authoritative, while the system underneath it shifts. I've seen teams protect these orphans with "keep it until someone complains"—but complaints rarely arrive as bug reports. They arrive as three-hour debug sessions that end with "wait, the docs are wrong?" Nobody logs that time. Nobody invoices the doc.

What usually breaks first is the connection to the actual workflow. The doc described how things were, not how things are. And because no single person owns it, every reader assumes someone else knows it's stale. Nobody does.

Open-source READMEs after maintainers leave

You find a neat CLI tool on GitHub. README looks clean—good badges, clear install instructions, a quick-start that actually runs. Then you hit the config reference. It lists five environment variables. Two have typoed names. One points to a service that was deprecated upstream three releases ago. The contributing guide still mentions the old CI platform that was replaced with GitHub Actions. The last commit to the docs folder is fifteen months old. The last release? Eighteen months.

'I stopped maintaining the project in March 2022. The docs still say I'm active. I'm sorry—I just didn't want to delete the repo.'

— maintainer, private Slack, 2023

That quote sticks with me. The maintainer didn't intend harm—they just couldn't stomach the final act of deletion or archive. So the README became a fossil, still warm, still hosting dead links and wrong commands. For the next contributor, this produces a specific flavor of debt: the confidence trap. They trust the first few paragraphs, so they blame themselves when the tool fails. They reinstall twice. They check their environment. They ask in an issue thread that hasn't been answered in nine months. Then they fork, fix the docs, and disappear—leaving the fixed version in their fork, unreachable by the next person who hits the same wall. That's the open-source pattern: the debt doesn't vanish, it just migrates to a new victim.

Internal wikis after reorgs

Most teams skip this: reorgs rewrite the org chart but leave the wiki untouched. Six months after a restructuring, a page titled "How to Request Access from the Old-Tech Group" still ranks first in search. The group no longer exists. The approval workflow now routes through a service desk that didn't exist when the page was written. New hires follow the instructions, submit a form to a dead group, wait three days, then ask their manager. The manager escalates to IT. IT shrugs. Someone eventually finds the right link—in a PDF attached to a meeting note from the reorg announcement.

That search cost repeats for every new hire, every quarter, every time the reorg reshuffles reporting lines again. And the doc stays untouched because editing it requires a permission group that was also reorged out of existence. The real trick here is threshold: at what point does the cost of fixing the doc exceed the accumulated cost of everyone stumbling through it? Most orgs never calculate it. They just delete the page two years later when a new platform engineer asks "what even is this?" and nobody knows. That's a clean cut, but the debt has already been paid, in small increments, by every confused newcomer along the way.

What Most Editors Get Wrong About Good Editing

Confusing brevity with clarity

The most seductive lie in legacy documentation is that shorter is always better. I have watched editors slash a 400-word troubleshooting guide down to eight bullet points—proud of the trim, blind to the wreckage. Brevity without context isn't clarity; it's a riddle for the next person. The original author included those extra sentences because someone, somewhere, had misinterpreted the obvious instruction three times. That backstory is invisible to the new editor. So you cut the preamble about the database timeout, and suddenly the next custodian spends two hours tracing an error that the old doc already solved. Short docs feel clean. They're often just empty.

The catch is that bloated docs also fail—nobody reads a wall of warning boxes. The trade-off lives in the middle: preserve the reason behind the rule, not every edge case. One concrete example stays; three hypotheticals go. That balance takes judgment, not a word-count target. Most editors default to the easiest path—delete everything—and call it "lean." It's not lean. It's debt.

Thinking 'update' means 'rewrite'

I see this pattern every quarter. Someone inherits a config guide from 2019, hates the voice, hates the formatting, hates the sidebar. So they rebuild the entire page from scratch. Six weeks later the new doc is live, the old one is gone, and nobody can find the critical note about the legacy API fallback that only existed in paragraph twelve of the original. Rewriting while ignorant of what you're deleting is not maintenance. It's arson.

A real update changes the parts that changed and leaves the rest alone. You don't need to modernize every sentence. You need to correct the port number, add the deprecation warning, and move on. The urge to stamp your own voice on inherited docs is strong—I have felt it myself—but it costs the next person confidence. They can't tell whether your rewrite introduced a fresh error or fixed an old one. Honest question: would you trust a stranger who replaced every paragraph in a manual you wrote?

“Rewriting a legacy doc to match your style is like repainting a house you just borrowed. You might like the color. The roof still leaks.”

— senior engineer, after a revert war on a Kubernetes runbook

That leaking roof is the ethical debt: you prioritized aesthetic consistency over institutional memory. The next custodian doesn't care about your elegant subheadings. They care about the one sentence that keeps the production database alive.

Ignoring the social layer of docs

Most editors treat documentation as a technical artifact—words on a screen, nothing more. Wrong order. Documents are social records. They encode who was trusted, who was excluded, which decisions were contested and which were rubber-stamped. Editing a legacy doc without understanding that social map is like editing a treaty without knowing who signed it. You might delete the paragraph that a senior architect fought to include, the one that subtly protects her team from a recurring blame cycle.

Field note: editing plans crack at handoff.

Field note: editing plans crack at handoff.

The anti-pattern here is the solo edit. One person reads the doc, makes changes in isolation, and publishes without talking to the people who lived through the history. That silence creates drift. The doc becomes technically accurate but socially untethered—nobody feels ownership, nobody defends it in a meeting, and eventually it rots. We fixed this in one project by requiring a two-person review for any deletion of content older than two years. It slowed edits by a day. It saved three weeks of rework later.

The hard part is that the social layer is invisible. You can't grep for it. You have to ask: "Who cares about this passage?" If you skip that question, you're not editing. You're accumulating regret for the person who opens the file in eighteen months.

Patterns That Actually Reduce Future Burden

Marking changes with provenance notes

Most editors drop a new paragraph into the doc and move on. I've done it myself — pasted a revised config block, closed the file, and silently hoped the next person would somehow know why that block replaced the old one. They won't. The trick that actually works: a one-line provenance note right beside the change. Not a commit message buried in git history — an inline note that says 'Replaced 2023-03 auth flow after SSO migration; old endpoint still valid for v1.2 clients until July.' That's not commentary. That's a handoff.

The catch is discipline. You have to write it while the context is hot — three weeks later you'll remember the what (you changed the endpoint) but not the why (because the upstream team deprecated it without notice). I've watched teams abandon this pattern because it feels redundant at the moment. It isn't. Without provenance, the next custodian spends half a day diffing the commit log, then another hour hunting down Slack threads that might — might — explain the decision. That's debt, plain as a missing semicolon.

One concrete rule: if your edit introduces a conditional or a fallback, annotate which scenario triggers each branch. 'If env=staging, use mock service (see ticket #142)' beats 'updated service config' every time. The act of writing the note forces you to check your own logic. You'll catch mistakes you'd otherwise ship and forget.

Using deprecation notices instead of deletion

Deletion feels clean. It isn't. When you delete a section that another page references — a parameter list, a status code table, a shell command that still works on older systems — you create a puzzle. The next person finds a broken link or a reference to something that no longer exists, and now they have to reconstruct what you removed. Worse, they might restore it incorrectly.

Deprecation notices fix this. Instead of killing the content, wrap it in a semantic block: [deprecated since 2.1 — use /api/v3/status instead]. Leave the original text visible. The cost is a few extra lines of screen space. The payoff is that the next custodian sees exactly what changed, when, and what replaces it. No archaeology needed.

A pattern that's worked for us: deprecation notices stay in the doc for two release cycles, then get a final review before actual removal. That review flag is the moment to check whether any downstream team still relies on the old behavior. If they do, the notice stays longer. If they don't, you cut with confidence. Most teams skip this step — they delete on the first pass and call it 'cleaning up.' That's how drift starts.

'Deletion is a commitment to having no future questions. Deprecation is a commitment to answering the questions you already know are coming.'

— senior editor, infrastructure docs team

Adding 'why' alongside 'how'

Your doc says how to run the migration script. The next person reads it, runs it, and the process works. Two months later, the script fails because the database schema changed. Now they have to decide: fix the script, or should the migration be done differently? The how alone gives them nothing to evaluate — they don't know whether the original method was a deliberate architectural choice or just what happened to work that Tuesday.

'Why' notes change this. A single sentence — 'We route through the staging cache here because prod can't handle cold-write bursts above 50 req/s' — tells the next custodian what constraint drove the design. When that constraint changes (prod gets scaled up, cache policy shifts), they can update intelligently rather than guessing. I've seen teams reduce handover time by roughly thirty percent just by adding a 'reason' line to each non-trivial procedure. That's not a stat from a study; it's what we measured after three handoffs in our own legacy rewrite cycle.

The hard part: 'why' notes require you to admit uncertainty. 'We set TTL to 300s because it matches the upstream rate limit — TBD if this holds under load.' That's honest. It tells the next person there's a question mark they should investigate. Most editors avoid that exposure. They shouldn't. A documented unknown is a known risk; an undocumented assumption is a ticking surprise. Which would you rather inherit?

Anti-Patterns That Teams Swear By—Then Abandon

Global find-and-replace without context

A senior engineer once replaced every instance of 'master' with 'primary' across three hundred pages. Took two hours. Looked clean in the diff. What broke: a glossary entry that defined 'master record' against 'child record'—now it said 'primary record' with no sibling term. Worse, a configuration walkthrough referenced 'the master node you just created'—that phrase disappeared entirely. The new custodian inherited a doc where step 4 asked them to do something they couldn't name anymore. Global find-and-replace treats words as tokens, not meaning. Teams swear by it for speed, then abandon it when the bug reports mention 'the missing thing we can't search for.'

Styleguide enforcement that strips voice

I watched a documentation lead run a passive-voice detector across an entire legacy library. Eleven thousand instances flagged. They hired a contractor to rewrite every one. The result? Technically correct. Also dead. Tutorials that once read like a colleague explaining a trick now read like a terms-of-service update. The original author had used 'you can optionally specify'—that became 'the parameter may be specified'. Not wrong. But the next editor couldn't tell whether the original writer had opinions about which approach worked best. That voice held context. Strip it out, and you strip the unwritten reasoning a future custodian desperately needs.

The catch is that consistency does matter—until it erases signal. Good styleguides leave room for a sentence fragment, a direct imperative, even a joke. Rigid enforcement turns docs into a surface that repels interpretation. You'll hit a point where the lint passes and the content fails. I'd rather have a page that's messy and usable than one that's pristine and empty of intent.

Deleting 'obsolete' sections without logging

Most teams skip this: a short markdown comment explaining why something was removed. They delete a section called 'Legacy API fallback behavior' because the new API is live. Clean. Feels good. Six months later, someone needs to understand why a certain edge case now returns a 500 instead of falling back. The section is gone. The commit message just says 'cleanup'. No context, no trace. That's debt—invisible until you accidentally step into the hole.

We cut twenty pages of deprecated endpoints last quarter. Now two new hires ask about the same missing feature every sprint. We can't even point them to a note.

— team lead, internal platform migration, 2024

What I've started doing instead: replace deleted sections with a single sentence and a date. 'Removed October 2023 — fallback no longer triggered after API v4 rollout. See commit 8f2a1c for discussion.' That sentence costs ten seconds. It saves days. The pattern feels like overhead until the first time you're the one staring at a gap, wondering what lived there.

Not every editing checklist earns its ink.

Not every editing checklist earns its ink.

One more habit that looks efficient but backfires: renaming files to 'archive' without updating cross-references. Honest—I've done it myself. Moved a folder to /deprecated, didn't grep for incoming links. The next editor found fifteen broken intradoc links scattered across unrelated guides. They didn't know whether the content was gone or just misplaced. They assumed the docs were untrustworthy. That assumption becomes the new baseline.

So the real anti-pattern isn't cleaning up. It's cleaning up without leaving breadcrumbs. Teams adopt these shortcuts because they work in the short term—the diff shrinks, the lint passes, the ticket closes. The cost shows up later, when someone else inherits the silence.

The Real Cost of Drift and Silence

The compounding toll of small omissions

One missing context line in a config block doesn't feel like debt. It feels like brevity. That sounds fine until the next custodian inherits seven repos, each with a config file that was edited "just enough" to make the current build pass. I have watched a team burn two full sprints reconstructing the implicit assumptions a previous editor had considered too obvious to write down. The pattern is brutal: each omission is individually defensible — the parameter was clear to you at the moment you wrote it. But three handoffs later, nobody knows why the flag exists, only that removing it breaks staging. That's not documentation debt; it's institutional amnesia, and it compounds faster than anyone admits.

The maintenance tax of orphaned docs

Every piece of documentation accumulates a carrying cost the moment it stops being revised alongside the codebase. Most teams skip this: they edit a page once, never return, and call it done. The catch is that an unmaintained doc doesn't sit still — it actively lies. A flagged paragraph about a deprecated API endpoint becomes a trap for the next engineer searching for answers at 11 p.m. on a Friday. We fixed this by adding a two-line metadata block to every legacy doc: date of last edit, and the name of the person who signed off on its accuracy. It didn't stop drift, but it forced visibility. Without that, you're paying a tax you can't see — the cost of time wasted on information that used to be true.

"We had a legacy doc that was 80% correct. That 20% of wrong caused a production incident that cost us three times the original documentation effort."

— Senior engineer, after a post-mortem that turned into a documentation rewrite

When 'good enough' becomes someone else's crisis

The dirty secret is that most editing shortcuts don't feel like shortcuts at the time. You're tired. The PR description says the change is "trivial." You decide to leave out the edge case because it happened once, two years ago, and surely nobody will hit it again. Wrong order. That's exactly the edge case that surfaces during the next quarterly release, except the person debugging it has no way to know it was ever documented — because you didn't write it down. The real cost isn't the incident itself. It's the silence: no ticket, no comment, no trace of the decision. Teams that swear by "move fast and document later" usually learn this lesson at the worst possible moment — during an on-call rotation where the person who knew the history is on vacation. You lose a day. The seam blows out. Returns spike. All because one edit was six words too short.

When You Should Walk Away From the Edit

Docs with No Clear Audience

If you can't name, in one sentence, who will read this page six months from now—walk away. The trap is seductive: the text exists, so surely it must be useful. But documentation written for "everyone" helps no one. I once inherited a deployment guide that alternated between Unix sysadmin jargon and marketing bullet points about "seamless onboarding." That page confused both groups equally. Editing it only made it longer. The real fix was deleting it—but the team flinched. So we left it untouched, and the next custodian spent three hours annotating it with "this doesn't apply anymore." Don't polish a document that has no reader. That's not editing. That's curating a corpse.

Worse: docs whose intended audience changed between paragraphs. You'll see a section written for external contractors, then a note for internal auditors, then a FAQ aimed at end users. No amount of copyediting can fix a document that doesn't know who it's talking to. The honest move is to hit Archive—or at minimum, add a banner: "This document has no clear audience. Proceed at your own risk." That hurts. But it's cleaner than pretending the page serves a purpose it never had.

Sections That Contradict Live Behavior

When the docs say one thing and the system does another, editing the prose is malpractice. I don't say that lightly. You can rewrite a paragraph until every comma is perfect, but if the underlying product changed last sprint and nobody updated the guide, your clean language becomes a trap. The catch is: you often can't tell which side is wrong. The code may be buggy. The docs might be stale. Either way, fixing the English doesn't resolve the discrepancy—it just makes the contradiction harder to spot. I have watched teams spend two weeks rewriting a "Troubleshooting" section that described a bug already fixed in the latest release. They made the instructions clearer, yet every new hire who followed them got confused because the bug was gone. Clearer lies are not better.

A rule of thumb: if a single step in your section references behavior you haven't personally verified against production—stop. Walk away. Leave a comment flagging the uncertainty, but don't edit the content. Editing implies endorsement. Silence implies skepticism. The latter is kinder to the next custodian.

Content Protected by Legal or Compliance

You don't edit legal language. You don't "clarify" compliance warnings. You don't rephrase disclaimers because they sound "stiff." This sounds obvious, yet I have seen well-meaning editors trim a liability paragraph from 300 words to 120, thinking they were being helpful. They were not. The original text was written by a lawyer who charges $800 an hour to anticipate precisely what a plaintiff's attorney might parse. Your job isn't to make it readable—your job is to leave it alone. The moment you touch legally-scoped content, you inherit liability. You become an implicit co-author, and if someone sues, your "improvement" will be Exhibit B.

Same goes for compliance checklists that regulators audit against. Editing a checklist to remove ambiguity might feel like an improvement, but ambiguity in compliance docs is sometimes intentional—it gives the organization room to interpret. By tightening the language, you inadvertently narrow that room. Next time the audit comes around, your cleaner document becomes a constraint nobody asked for. Walk away. Mark the section as "legal / compliance—don't edit" in a comment, and move on.

Editing a page because you can is not the same as editing a page because you should.

— overheard from a senior tech writer after she deleted her own changes

That hurt when I heard it. She'd spent three days polishing a migration guide that contradicted the current API response format. She caught the mismatch, reverted her edits, and left a single comment: "This page references v1 endpoints. Verify against v2 before editing further." The next custodian thanked her—not for clarity, but for restraint. That's the real skill: knowing when your edit does more damage than leaving a mess alone. Mess is honest. Polished misdirection is debt with a bow on it.

Open Questions That Still Divide Editors

Should you preserve the original author's voice?

Half the editors I've worked with treat the original author's voice like sacred text—preserve every idiom, every weird comma splice, because that's "authentic." The other half strip it out like old wallpaper, replacing personality with a flat corporate monotone that passes for consistency. Neither side is wrong, exactly. The trade-off hits when you inherit a doc that uses "utilize" seventeen times and nobody knows if that was a deliberate choice or just the author's bad habit. Preserve the voice and you're honoring a ghost. Strip it and you might be sanding off the one thing that made the doc readable to the people who actually used it.

I watched a team spend three weeks debating whether to keep a retired engineer's eccentric terminology—terms like "the juice" for electrical load. The new custodian wanted them gone. The old crew refused. Meanwhile the doc sat frozen. The real cost wasn't the debate; it was the silence that followed. Nobody touched that section for eighteen months.

The catch is that voice fades anyway. What feels like a vivid authorial fingerprint today reads as clumsy obstruction in six months. You're not protecting the author. You're protecting the reader's ability to move fast. But if you flatten everything to standard English, you lose the texture that made the doc feel like it came from people who actually built the thing.

Flag this for editing: shortcuts cost a day.

Flag this for editing: shortcuts cost a day.

— I've started asking: "Would the next person be able to fix a bug from this page without calling anyone?" That question answers the voice problem faster than any style guide.

Is it okay to delete content with no known owner?

This is where editors split into camps. Camp One says: orphan content is liability—delete it, burn it, never look back. Camp Two says: that orphan might be the only documentation for a critical process someone forgot to migrate. Both are right. Both are wrong. The problem isn't the deletion; it's that you can't evaluate risk when no one remembers why the content exists.

Most teams skip this: run a simple tombstone test. Tag the orphan with a date and a note: "If no one objects in 90 days, this gets removed." I've seen this work beautifully on a legacy migration project. Fourteen orphan pages were flagged. Exactly one got a response—an engineer who said "that's the only place we describe the rollback procedure for the old database." Thirteen disappeared quietly. The one that stayed probably saved someone a week of digging.

That said, the anti-pattern is pretending you can evaluate orphan content in isolation. You can't. The context that made it useful is almost always missing—the Slack thread, the meeting where they decided to deprecate something, the Jira ticket that got closed without a comment. Deleting without a trace is fine. Deleting without a trial period is reckless.

Honestly—the hardest part isn't deciding. It's that the people who could tell you why the content exists are usually the same people who left the company six quarters ago. You're guessing. And guessing beats leaving a corpse in the file tree.

How much context is too much?

New editors over-contextualize. They add introductions, background sections, "why this matters" blurbs—until the document is 40% preamble and 60% actual instruction. I've seen a deployment guide with three pages of architecture history before it told you which button to click. The original author just wrote "run deploy.sh — if it breaks, check the logs." That's too little. The rewrite is too much. Where's the middle?

Context is like salt: the right amount makes the meal. Too much and you're just eating salt with a side of food.

— paraphrased from a senior engineer who walked out of a doc review

The pattern I've found useful: put context in one place, link to it, and never repeat it. If a procedure depends on knowing why the database is sharded, write that in a sibling doc called "Database sharding rationale" and link once. Don't re-explain it in every section that touches a shard. The reader who needs the context will follow the link. The reader who doesn't—who just wants the command—won't get buried.

What usually breaks first is the link itself. Teams write great context docs, then reorganize the wiki and forget to update the cross-references. Suddenly your terse procedure doc is useless because the linked "why" page returns a 404. Context isn't valuable if it's invisible. So maybe the real question isn't "how much context"—it's "how will you keep the context alive when everything else shifts around it?" That question doesn't have a clean answer yet, and that's why it still divides good editors.

Next Experiments to Try With Your Inherited Docs

Start a change log for the next person

Most teams skip this because they assume the next editor will read git blame. They won't. Git blame tells you who touched a line, not why they left a half-finished table or deleted that weird paragraph on vendor contracts. One concrete experiment: drop a plain-text file called `doc-log.md` into the root of your docs folder. Every time you make a call that feels even slightly risky—rewriting a process that was technically correct but confusing, removing a section nobody used but nobody admitted they needed—write a single sentence about it. That's it. A sentence. "Removed the onboarding checklist because it duplicated the wiki; check wiki before restoring." The next custodian will curse you a little less.

The catch is that change logs rot fast if they're not part of the edit flow. I've seen teams start strong, log ten entries, then abandon the habit because the docs were "stable." Stable means nobody's looked at them in six months. So tie the log to something painful: every time you fix a bug in the documentation—not a typo, a real logic error—log it. That creates a pattern. After three months, you'll see which sections eat the most edits. That's your debt hotspot, clear as day.

Tag sections by confidence level

You inherit a doc. Half of it's solid—tested, recent, lived. The other half is cargo-culted from a meeting note someone wrote at 2 AM. Most editors treat all paragraphs as equal. Wrong order. Instead, drop a confidence marker in the heading or the first line: `[CONFIDENCE: HIGH]` or `[CONFIDENCE: SUSPECT]`. It's ugly, but it works. The next person knows exactly where to spend their limited attention. They don't waste an afternoon verifying a process that's still current when the real landmine is three sections later—something labeled "minor update" that's actually a structural change.

Honestly—this one gets pushback. Teams say it looks unprofessional. But what's more unprofessional: a transparent warning that a section might be stale, or a silent time bomb that wastes someone's sprint? Trade-off is you'll occasionally tag something as low confidence that is correct, and the next editor will spend ten minutes double-checking. That's a cost. But it's a fraction of the cost of assuming everything is reliable and finding out otherwise during an outage.

Run a 'debt retrospective' after three months

Set a calendar reminder for ninety days after you finish editing a batch of legacy docs. Block thirty minutes. Open the docs again and read the diff between what you delivered and what's there now. Not the whole document—just the sections you touched. What changed? What did the next editor add, remove, or revert? Most people never close this loop. They hand off the edit and assume it's settled. It never is. The docs drift, someone silently reverts your careful restructuring because they "liked the old way," or a feature deprecation makes your rewrite obsolete before anyone noticed.

One team I worked with found that a section they'd spent two days untangling was completely rewritten by a junior dev within a month—the dev didn't know the log existed. That's not failure; that's signal. The junior's rewrite was worse by any objective measure, but it was closer to how new hires thought. The debt retrospective showed us that we'd edited for correctness when we should have edited for onboarding speed. The next time, we wrote for the person who'd never seen the system. A single retrospective changed our entire editing heuristic.

'The first edit is never the last edit. The question is whether each edit leaves the next person better off or just differently confused.'

— project lead, after a particularly painful migration

Try the retrospective once. If it reveals nothing, drop it. But odds are you'll find one pattern that makes you wince—and that wince is the most actionable data you'll get all quarter. Document it in the change log you started. Then tag that section with low confidence. Run the loop again in three months. The debt doesn't disappear—you just stop carrying it alone.