One product, many repositories, one source of truth

Your product is one thing to the people who use it. Internally it is a web app, a backend API, a mobile client, a background worker, and some infrastructure — five repositories, five histories, five sets of owners. Nobody set out to split the product into pieces nobody reads together. It happened one reasonable decision at a time.

The problem shows up the moment someone asks a whole-product question. Where does a followed store get stored, and which services notice when it changes? The answer lives in four repositories, and there is no document, dashboard, or person that holds all four at once.

Every tool you own reads one repository at a time

This is the structural reason the gap never closes on its own. Your issue tracker scopes to a repository. Your code search scopes to a repository. Your CI, your review, your ownership file — all of them draw their boundary at the same place, the repository edge. The tools are not wrong; they were built for the unit teams actually commit to.

But the product is not a repository. It is the seam between them: an event the backend emits and the worker consumes, a field the API renames and the mobile client still expects, a feature that is half-built in one repo and fully wired in another. None of those live inside a single repository, so none of your per-repo tools can see them. The knowledge that spans repositories lives only in the heads of the few engineers who have worked across all of them — and it leaves when they do.

Take a concrete one. The backend renames store_id to merchant_id in a pull request that, from inside the backend repository, looks complete and correct — its own tests pass, its own reviewers approve. But the mobile client still sends store_id, and the worker still keys its notification lookup on the old name. Nothing in the backend's repository knows those two consumers exist. The break is real, it spans three repositories, and not a single per-repo tool is positioned to catch it. It surfaces in production, or in an incident channel, or in the head of the one engineer who remembers that the worker reads that field.

So the whole-product view gets rebuilt by hand, every time it is needed. Someone opens each repository, reads enough to reconstruct how the pieces connect, and holds the result just long enough to answer the question in front of them. The next question starts from zero, because the reconstruction was never written down anywhere the tools could keep it current.

What it costs

The cost is not one big failure; it is a tax on every cross-repo decision.

A feature request arrives and estimation stalls, because no one can enumerate the services it touches without a day of spelunking. A spec ships describing three of the four repositories involved, and the fourth surfaces as a surprise in code review. A product manager answers a stakeholder confidently and is quietly wrong, because the part of the system they could not read is exactly the part that mattered. Each of these is small. Together they are why cross-repo work always feels slower than it should.

What actually closes the gap

• Treat the set of repositories as the unit, not each repo. The thing worth describing is the product, which means the artifact you maintain has to span every repository the product lives in — not one document per repo that drifts apart.
• Anchor the description to the code, not to memory. A whole-product view assembled once by hand is stale by the next merge. One that is derived from the repositories can be regenerated when they change, instead of decaying between the dates someone had time to reconcile it.
• Answer in product language, with the code as evidence. The reader making the decision is a product manager, not the engineer who happens to know the seam. The connection between services has to reach them as product behaviour with the source attached, not as a diff they are told to learn to read.
• Keep the boundary honest. Reading every repository to explain the product is a different job from changing any of them. A tool that crosses repositories to understand them should not also be the thing that edits them — the value is the map, and the map is trustworthy precisely because making it touches nothing.

WeaveSpec is built on the bet that the missing artifact — one product view, derived from the many repositories, kept current as they change — is worth having on its own. Connect the repositories that make up a product, and the seams between them stop being the thing only three people understand.