> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whyfile.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 0016 intent query layer

# ADR-0016 — Intent query layer (explain / list-intent / why)

**Status:** Accepted
**Date:** 2026-07-05

## Context

The intent layer was write-only: nothing read `graph.enriched.json` back. The product wedge is "why is
the code like this?", so a read/query surface is the payoff.

## Decision

Add three LLM-free, read-only subcommands over the enriched graph, with the pipeline remaining the
no-subcommand default (backward-compatible):

* `explain <node>` — resolve the node (exact id, else rapidfuzz over labels), then traverse: a non-intent
  (code/document) node → the intent nodes that motivate it via **intent-origin** `rationale_for` edges; an
  intent node → its own claim/rationale + the nodes it explains + its Pass-C relations (supersession
  surfaced). 1-hop only.
* `list-intent [--kind K] [--min-confidence F]` — the intent inventory as JSON.
* `why "<question>"` — rapidfuzz `token_set_ratio` retrieval over intent text; top-N ranked, with a
  `no_strong_match` status below a cutoff. Retrieval, not synthesis — the agent draws the conclusion.

Two data-model facts are load-bearing (ADR-0006): the enriched graph is node-link, so edges are under
`links` (not `edges`); and `rationale_for` is overloaded (graphify's base graph emits code→code
`rationale_for`), so intent motivators are found by filtering to intent-origin sources.

Each query invocation emits exactly one JSON object and exits from its `status` (0 / 2), consistent with
`--dry-run`/`--doctor`. `--format text` renders the same object for humans.

## Consequences

* Agents can ask "why" and get structured claims/rationales/alternatives/relations with stable exit codes.
* Query is deterministic and free (no LLM); `why` is lexical (best-effort), with scores exposed so callers
  can judge weak matches.
* No graph mutation, no multi-hop traversal, no embedding retrieval (deferred).