What Breaks When Your Code Index Goes Stale

You rarely catch a stale index directly. You catch its symptoms, and they look like this:

• Your assistant references a symbol you're sure you renamed or deleted.
• "Who calls this?" returns a list missing the caller you added yesterday.
• Answers describe the architecture from before a merged refactor.
• Everything is right on main and subtly off on your feature branch.
• A suggestion assumes the version of a function you are in the middle of rewriting.

If you're seeing any of those, the picture and the code have diverged. The rest of this is what's actually happening underneath, and what to do about it.

A stale index doesn't fail — it answers. A down service times out and a broken build goes red, but an index whose snapshot is old still responds to every question, completely, about a version of your codebase that no longer exists.

Three ways it bites

The deleted function that still exists. You removed applyDiscount this morning. A stale index still lists it, still shows its callers, still offers its source. An AI assistant reading that index will happily reference the function you deleted — and even suggest calling it from new code. The wrongness compounds: code written against ghosts fails in ways that look like your mistake, not the index's.

The branch that isn't there. Indexes that track one branch — usually the default — are wrong about every other branch in proportion to how far it has diverged. That's the cruel part: the deeper you are into a refactor, the more you lean on tooling, and the more wrong a main-only index becomes. Its answers are most misleading exactly when you need them most.

The uncommitted gap. Even a perfectly current index is built from committed code. The function you are editing right now, the file you just created — those live in your working tree, invisible to anything keyed to commits. Mid-change, your assistant can be reading the previous version of the very function you're rewriting, and its suggestions will quietly assume your edit never happened.

Why "mostly fresh" is worse than obviously wrong

An index that's obviously broken gets ignored, which is safe. An index that's mostly right gets trusted, which isn't. If 95% of answers are current, you stop checking — and the 5% arrive with no marking, embedded in refactors and reviews where a stale caller list means a missed breakage.

What honest tooling does instead

Three behaviors separate an index you can trust from one you merely use. They're worth demanding of any tool in this category, ours included:

Refuse rather than substitute. Ask about a branch that hasn't been indexed, and the honest response is "this branch has no snapshot — here's what I could verify locally," not a silent answer from main dressed up as current. A refusal is annoying for a moment; a substitution is wrong invisibly. cix does the former: a query on an unindexed branch says so explicitly, rather than answering from another branch.

Say where the answer came from. Every answer should carry its provenance — built from which commit, served from committed code or your working tree. When something looks off, the first question is "how old is this?", and that question should be answerable from the response itself instead of by archaeology.

Close the uncommitted gap deliberately. The working tree needs an explicit path into visibility — reading a file as it is now, making dirty and untracked files findable by symbol name — so that "index the repo" and "see what I'm doing right now" are both possible, and you always know which one you're getting.

The fix, which is boring

Reindex. Then arrange things so you don't have to remember: prefer tooling that reindexes on push, so freshness is a property of the setup rather than a habit you maintain.

For the mechanics on cix specifically, see Keep your index fresh and Understanding index state, and Branches and worktrees for how branch-scoped answers behave.

If you're evaluating something else, the thing to check is whether it will tell you how old an answer is without you having to work it out.