Resolve architectural decisions for a code change by matching explicit scope—repository, path, service, language, dependency or environment—before using semantic similarity. Return the active records, the exact reason each matched and a stable citation. Deterministic scope should outrank inferred relevance whenever both are available.
Applicability is the missing retrieval problem
Search answers which documents resemble a query. A scope resolver answers which decisions govern a change. Those are not the same question: an obsolete proposal may be textually similar, while an accepted data-residency rule may use none of the vocabulary in the task description.
A resolver should exclude superseded and rejected records by default, preserve their discoverability for history, and explain every inclusion. An unexplained relevance score is weak evidence for a governance decision.
Use deterministic signals first
Begin with facts available from the repository and change set. Exact signals are reproducible at a pinned commit and can be tested without guessing the user's intent.
- Repository, directory and file-pattern matches.
- Service or component identity from a maintained catalogue.
- Language, framework, configuration type or deployment environment.
- Dependency edges, code ownership and declared data classification.
- Decision lifecycle, supersession and explicitly granted exceptions.
Add semantics as discovery, not authority
Task descriptions and code symbols can surface records whose scope metadata is incomplete. Treat that result as a candidate set, then resolve each candidate to the reviewed record and current lifecycle. Semantic retrieval is especially useful before the exact files are known; deterministic resolution becomes stronger as a plan turns into a patch.
Re-run the resolver when the agent adds files or changes direction. Applicability is a property of the evolving change, not only of the initial prompt.
Return reasons that a reviewer can challenge
A useful result includes the record ID, status, source revision and a reason such as ‘path matches services/*/events/**’. It should also distinguish a direct scope match from a semantic suggestion and expose conflicts instead of silently choosing one decision over another.
{
"id": "ADR-0042",
"status": "accepted",
"match": "path",
"reason": "src/events/** is in declared scope"
}