From one feature request to four repositories

Here is a request, phrased the way requests actually arrive:

Users should be able to follow a store. When a new deal appears at a store they follow, send a web notification, a mobile push, and an email.

One sentence. Two weeks of calendar time before anyone writes code, most of it spent finding out which parts of the system that sentence lands on.

The discovery tax

Nobody schedules this work, which is why nobody notices its cost. It starts with a product manager who cannot answer "which repositories does this touch" and ends with two or three engineers independently re-reading the same services to answer it.

For the request above, the honest answer is somewhere between four and seven repositories: the API that owns stores and deals, the web client, the mobile app, a worker that reacts to events, maybe a notification service, maybe an analytics repository that needs new events, and whatever holds the infrastructure the worker runs on.

Getting to that list is not hard work. It is tedious work: open each repository, grep for the concepts in the request, follow the imports, find out that push tokens are stored in a table you did not know existed, discover that the email path goes through a provider nobody has touched in a year. Then a decision changes, and the same walk happens again.

The tax compounds because none of it is written down in a form the next feature can use. The discovery for the "follow a store" feature is thrown away when the spec is finished. The next request, which touches three of the same four repositories, starts from zero.

Doing the reading once

The alternative is to make the reading a property of the project rather than of the feature. That means analysing the repositories up front, in stages, and keeping the result.

Inventory. File tree, sizes, language mix, manifests, detected frameworks, service entry points. Cheap, mechanical, and it already answers questions people currently answer by opening repositories one at a time.

Static extraction. Classes, functions, routes, models, events, queues, dependencies, environment variable names, references to external services. This is where "which endpoints exist" stops being an opinion.

Semantic summaries. A summary per file, per module, per domain, per repository. These are what let a request written in product language find code written in engineering language — the request says "follow a store", the code says MarketFollow, and something has to bridge that.

A cross-repository graph. Repositories, services, endpoints, entities, events, queues, screens as nodes; calls, produces, consumes, reads, writes, imports as edges. This is the artefact that does not exist anywhere today. Each repository knows its own imports. Nothing knows that the mobile app's notification handler is downstream of an event the API emits.

Retrieval per request. For a given feature request, pull only the repositories, modules, routes, entities, events and tests that are actually relevant, then expand along the graph edges:

MarketFollow
  → belongs to Market
  → related to the DealCreated event
  → consumed by NotificationWorker
  → calls FirebaseService

That expansion is the discovery walk an engineer does by hand, except it runs in seconds and it does not skip the repository nobody remembered.

What comes out

The output of that walk is not "an answer". It is the set of documents the feature needed anyway:

• A product requirements document — user stories, acceptance criteria, scope.
• A technical design document — proposed approach, API changes, data model changes, the event and notification flow.
• The list of affected repositories, with a reason attached to each one.
• Test scenarios derived from the acceptance criteria.
• Risks and dependencies, including the ones that come from ordering — the mobile release that cannot ship before the API change.
• After approval, Jira epics, stories and tasks, split by repository.

Every non-obvious claim in those documents carries its evidence: a file path, a commit hash, a line range. Not for the product manager, who has no reason to open them, but for the tech lead who reads the technical document and wants to know whether the paragraph about the existing notification service is describing reality or describing an average of the internet.

Where the human stays

The generated documents are a first draft with citations, and a first draft is exactly what they should be treated as. The parts a model cannot know are the parts that matter most: which of three valid approaches fits the team, what the actual priority is, which dependency is politically expensive, whether the analytics events are worth the delay.

So the flow keeps people at the two points where judgement lives. Someone edits the document, and someone with the authority to approve marks it final — which is also the precondition for anything being written to Jira. Nothing reaches your tracker because a job finished.

What is removed is not the thinking. It is the part of the process where four people separately open the same four repositories to rediscover the same four facts, and then one of them types those facts into a document that starts going stale the moment it is saved.

That is the work WeaveSpec is built to do once, and keep.