Querying the intent layer

Once a run has produced its outputs, three subcommands read them back: read-only, LLM-free, and free of charge (no backend call, no cost). Each prints exactly one JSON object on stdout by default; add --format text for a human-readable render instead. All three accept --graph PATH (default graphify-out/graph.json, same as the pipeline; may be given before or after the subcommand name) and exit 0 for a status of ok/no_strong_match, 2 for not_found/ambiguous/no_intent_layer (see Exit codes; full JSON schemas are in AGENTS.md). explain <node> resolves <node> (an exact node id, else a rapidfuzz match over node labels) and explains it: for a code/document node, the intent node(s) that motivate it (the intent-origin rationale_for edges pointing at it); for an intent node, its own claim/rationale, the node(s) it explains, and its Pass-C relations (a supersession is surfaced as superseded_by on the superseded node). Requires graph.enriched.json; returns status: "no_intent_layer" (exit 2) if it doesn’t exist yet.

whyfile explain AuthModule
whyfile explain i_d1 --format text

list-intent [--kind decision|mechanism|constraint|tradeoff] [--min-confidence F] returns the intent inventory, optionally filtered by kind and/or a minimum confidence_score.

whyfile list-intent --kind decision --min-confidence 0.8

why "<question>" ranks intent nodes against free text with rapidfuzz token matching and returns the top --top (default 5) by score (0-100); a top score below the cutoff (60) still returns its results, just with status: "no_strong_match" so a caller can tell the match was weak.

$ whyfile why "why does Pass A use a stronger model than the others" --top 2 --format text
Top 2 match(es) (no_strong_match):
   56  [tradeoff] Per-pass tiering protects Pass A quality — Running Opus on every pass was the
       cost bug; tiering lets cheaper models handle most passes, but Pass A is deliberately held
       on sonnet because its output quality matters enough to justify the higher tier.
   56  [decision] Per-pass model tiering — Passes B/C/D need less reasoning than A, so downgrading
       them to cheaper haiku captures most of the cost saving without hurting quality — but a
       user's explicit model choice still wins.

list-intent and why don’t require graph.enriched.json; they fall back to the .whyfile.json sidecar when it’s the only artifact present. The pipeline itself is unchanged: running whyfile with no subcommand still runs the extract/anchor/relate run described above.

​Querying the intent layer

Querying the intent layer