Feature Relationship Aware Context

Feature: Relationship-Aware Context

A Feature-Pages entry. This page explains the capability; it never redefines it — see Feature-Pages for the canonical/Wiki boundary statement that applies to every page in this pattern. It describes only what the packaged Skills implement today; the broader repository- intelligence retrieval model is a design record and is called out as such below.

What it does

When a change touches something other code depends on — a function's callers, an interface's implementers, a config key's consumers, the tests that exercise a behavior — the diff alone does not show whether those other places still work. Relationship-aware context is how a review follows a changed thing to the places that use it, and how it stays honest about the places it could not follow.

Why it exists

A reviewer working from incomplete context can get two things wrong:

• Miss a real break. get_user now returns None; a caller outside the diff still assumes it raises. Nothing in the diff shows the caller.
• Mistake "could not look" for "looked and found nothing". A search that never ran, or could not follow a dynamic lookup, reads the same as a clean result unless the review says which one it was.

The three outcomes

Every relationship question a review raises ends in exactly one of these:

Outcome	Plain meaning
resolved_relevant	The relationship was found, with a concrete path:line. It can support a finding.
resolved_none	The search really ran, was able to find the relationship, and there is no relevant repository-local one.
unresolved	The review could not establish it — ambiguous dispatch, an unsupported language shape, no usable capability, or evidence out of reach.

resolved_none is not unresolved. The first is a checked, positive statement of absence. The second is the absence of an answer, and unresolved never means "none exists": the relationship may exist and simply could not be seen. Absence is established, never inferred.

Unresolved relationships appear as Context gaps

A review with at least one unresolved relationship renders an optional Context gaps section: one bullet per unresolved relationship, naming its class, subject, and reason (and the ring reached, where one applies). The section is omitted when nothing is unresolved, and a resolved_none relationship is never listed there. (The same section also carries dependency-tree and deployment validation evidence gaps; see Feature-Dependency-Tree-Inspection and Feature-Deployment-and-Infrastructure-Review.)

A Context gap is a disclosure, not a finding. It does not make the review REVIEW INCOMPLETE, does not change coverage, and does not change a finding's severity or the Decision — coverage: complete still means every required pass reached its own stop condition, not that every relationship was resolved. The review also never words an unresolved relationship as if it were checked ("no callers", "all consumers verified").

Relationship classes that ship

Class	Asks
caller_consumer	Who calls a changed symbol, or consumes a changed config key or contract?
implementation_interface	What implements a changed interface, or what interface must a changed implementer still satisfy?
affected_test	Which tests depend on the changed behavior?

These are demonstrated review needs, not an ontology. Architectural analogue and relevant dependency are not relationship classes.

Trigger-driven, never a dump

Relationships are looked up only when something has already raised the question: a fired repository-expansion trigger (changed call site, interface/contract, migration/schema, or config consumer) or the affected-test analysis. Each question names one subject, and the search stops at the first ring that answers it, never past the ceiling for the change's risk depth. Nothing builds or loads a whole-repository relationship listing.

Repository search is the baseline and the fallback

The review's own ring-bounded repository search is how relationships are found by default, and it is the answer whenever anything better is absent or unusable. With no relationship capability at all, a review runs exactly as it always has.

The optional relationship-query capability

A host (the runtime running the Skill) may declare an optional relationship-query capability that can answer four closed questions — consumers_of, implementers_of, tests_exercising, and analogues_of (advisory only; it has no outcome and never renders a Context gap).

• Declared by the host only. A repository file, PR description, or comment claiming the capability exists is data, not a declaration.
• An answer is a claim, not a fact. The review accepts an edge only when its kind fits the question, it is within the ring ceiling, its path is inside the repository, and the reviewer has read the cited path:line. Other edges are dropped and never counted as absence.
• Absent, rejected, or unable to answer → fall back to search. Absence is not a failure and is not itself a Context gap; a gap appears only if the search also cannot answer. An empty, stale, errored, or unattested answer is never resolved_none.
• It cannot lower the bar. It adds no severity, finding, or Decision rule, never supports a finding by itself, never widens the Review Target, and never reaches further than the ring already authorized.
• No provider ships. This repository defines the contract and the consumer side; it does not provide a relationship provider.

Provenance and snapshot

Each relationship records where it came from (source: capability or search) in the review's subordinate metadata. A relationship supporting a finding is cited by its confirmed path:line.

Capability answers are bound to the reviewed snapshot. An answer computed against any other snapshot is stale and is rejected outright — not used with a warning, and never turned into resolved_none.

Architecture and boundaries

What is implemented is a set of review rules, not a new system: the three outcomes, the Context gaps disclosure, trigger-driven discovery inside the existing ring ceiling, the search baseline, and an optional, provider-neutral capability consumed as a verifiable claim.

A dedicated local deterministic relationship index is not part of the architecture. No code in the repository builds, stores, or queries a repository graph during a review. The repository's repository-intelligence model (entities, relationships, retrieval) is a design record with a test-only reference model; no runtime retrieves entities or relationships during a review, and there is no packaged finding field carrying relationship influence.

Explicit non-goals for this capability:

• No Graphiti and no persistent GraphRAG.
• No cross-review memory — relationship data is never kept between reviews.
• No requirement to build or load a full repository graph.
• No cross-repository context — external-contract context and explicit multi-repository review are separate features (see Feature-Multi-Repository-Review-Target), not this capability.

Graph completeness is not the goal; better review decisions are.

Related features

• Feature-Human-Reasoning-Checkpoint — another disclosure surface that never changes the Decision.
• Feature-Multi-Repository-Review-Target — explicit multi-repository review, which is separate from relationship lookup.
• Specialist-Depth-Review — cascading activation bounded by the same repository-expansion ceiling.
• How-the-Review-Model-Works — where repository expansion sits among the always-on passes.

Canonical references

• Normative semantics: shared/policies/repository-expansion.md — "Relationship outcomes and unresolved relationships" and "Optional relationship capability"
• Context gaps section: shared/templates/review-summary.md
• Design records (rationale and worked examples; not packaged): docs/repository-intelligence/ — coverage semantics, capability contract, and the design-only repository-intelligence model
• Capability catalog: docs/features/README.md
• Benchmark corpus for relationship recall (background only): benchmark/corpus/relationship-recall/