How to resolve which architectural decisions apply to a code change

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"
}