The Oracle

What it is

The Oracle is the project’s memory. You give it context files in whatever form you already have them:

• standards and conventions
• decision records and design docs
• READMEs and runbooks
• ticket and PR history
• dependency lists
• answers engineers have given before

Agents and people then ask it questions in plain English, at any point in their work.

It deliberately asks very little of you. There is no schema to fill in and no special format to learn. If it is text, it can go in.

How it works

It is “ask your docs”, built the standard way, with one addition: before searching, the Oracle adds context to every question.

1. Index

1. Collect. Gather every context file from the repo and any connected sources.
2. Split. Break each file into passages of a few paragraphs.
3. Add context to each passage. Prefix each passage with a short line saying where it comes from and what it covers. For example: “From engineering standards, section Dependencies: rules for adding third-party packages.” A passage that only says “these must be approved first” is then still findable.
4. Embed. An embedding model turns each passage into a list of numbers that represents its meaning. Passages about similar things get similar numbers, even when the wording differs. “Carousel” and “image slider” end up close together.
5. Store. Save the passages and their numbers in a vector store: an embedded one when running locally, Postgres with pgvector on a server.

Indexing runs again on every merge, so the Oracle always matches the code.

2. Ask

An agent asks a question mid-task. The question can be short and vague, which is how real questions usually are.

3. Expand

Short questions are hard to search well. So before searching, the Oracle expands the question with what it already knows about the asker:

• The task. The brief, the work item, the area of the product.
• Where the agent is working. The files and modules in its footprint.
• Related terms. Synonyms and the names things go by in this project.

From this it writes a few search queries, not one.

4. Retrieve

Each query is embedded and compared against every passage. The closest matches from all the queries are merged, duplicates removed, and ranked. Matches below a similarity threshold are dropped, so weak results never pass as evidence.

5. Answer

A model writes the answer only from the retrieved passages, and cites each one. If the passages do not contain the answer, it says so instead of guessing.

6. Escalate and learn

When the evidence is thin or conflicting, the question goes to the engineer who owns the work, with the passages already attached. The engineer’s answer is saved as a new context file and embedded. The next agent that asks gets it straight from the Oracle.

Every question gets asked of a human at most once.

A worked example

A frontend agent is building an image gallery for task PAY-512. Mid-task it asks:

Is there any precedent for using a swiper library?

Expand. The Oracle adds the task context (frontend, the gallery page, task PAY-512) and related terms. It searches for:

swiper library precedent
carousel or slider component in the frontend
image gallery implementation
rules for adding a third-party package
frontend bundle size limits

Retrieve. The closest passages come back:

docs/standards.md#dependencies
  "A small, well-documented and safe package may be added when
   there is a clear need. Prefer mature projects with a permissive
   license and active maintenance."

apps/shop/package.json
  (the full dependency list: no carousel or slider package)

decisions/0007-frontend-bundle-budget.md
  "Heavy UI libraries must be lazy-loaded on the pages that need them."

Answer.

No carousel or slider library is used so far. Engineering standards
allow a small, well-documented and safe package when there is a clear
need, so Swiper is fine: it is mature and well documented. Per the
bundle budget decision, lazy-load it on the gallery page only.

Sources: docs/standards.md#dependencies, apps/shop/package.json,
         decisions/0007-frontend-bundle-budget.md

Learn. When the change merges, the record that Swiper is now the project’s carousel library is added to the context. The next agent that asks hears: “Yes, Swiper, added in PAY-512. Follow its use in the gallery page.”

What makes answers good

The Oracle is only as good as what you feed it. Three habits make the biggest difference:

• Write decisions down. A one-paragraph decision record beats a long chat thread nobody can find.
• Keep docs current. Stale docs mislead agents more than missing docs. EILAID flags docs that have drifted from the code.
• Let answers flow back. Every question an engineer answers becomes context. After a few weeks, most questions answer themselves.

Where it can grow

The first version is deliberately simple: embeddings, query expansion and cited answers. Extra lookups can be added later as tools the Oracle calls alongside search, without changing how anyone asks questions:

• exact code search
• a live dependency inventory
• package health checks
• the ledger of in-flight work