git:20260731.479f3e8 to git:20260820.6962ca7

- ## Overview

-

- "Discovery" is the work of finding and understanding the code relevant to a task before you change it — the single largest, easily-wasted token cost in a session. Reading whole files to answer "where is X? what calls Y? how does Z flow?" is expensive. When [Graphify](https://github.com/Graphify-Labs/graphify) is available, a pre-built code graph answers those questions by traversal and hands you back the exact `source_location`s to read — so you `Read` a handful of precise spans instead of grepping the tree.

-

- This skill is the **single source of truth** for that routing. It is intentionally loose-coupled and version-tolerant: Graphify is optional and pre-1.0, so every step is guarded and **falls back to plain Glob/Grep/Read** when Graphify is missing, unhealthy, stale, or the graph is empty. Discovery must never hard-block on it.

-

- Graphify ships its own `/graphify` skill (registered by `graphify install`). This skill does **not** reimplement graph building or querying — it decides *when* to reach for Graphify and defers the "how" to Graphify's CLI / skill.

- ### 1. Detect and health-check

-

- - **Binary on PATH?** `command -v graphify` (equivalently `graphify --version`).

- - **Graph already built?** `graphify-out/graph.json` exists at the repo root.

- - **Graph fresh?** A graph is only trustworthy for the tree it was built from. `graph.json` records `built_at_commit`; compare it to the SHA of the tree your answer is about (`git rev-parse HEAD` for the working tree). `graphify check-update .` also flags pending staleness. If they diverge, the graph is **stale** — refresh it (step 2) or narrow to grep for the changed area (step 5).

-

- If the binary is absent → **skip to step 5 (fallback)**. Do not prompt the user to install it; the SessionStart tool-check already surfaces it as a recommended tool.

-

- ### 2. Build or refresh if missing/stale (code-only, no API key)

-

- If `graphify` is installed but `graphify-out/graph.json` does not exist, build a code-only graph. This is pure local tree-sitter AST — **no LLM, no API key, seconds** on a typical repo:

-

- ```bash

- graphify extract . --code-only

- ```

-

- If the graph exists but is **stale** (step 1: `built_at_commit` ≠ your tree's SHA, or `check-update` flags it), refresh it incrementally — AST-only, still no key:

-

- ```bash

- graphify update .

- ```

-

- - In interactive commands (`/orc:start`, `/orc:plan`), mention it's happening ("Building/refreshing a code graph for cheaper discovery…").

- - In a dispatched agent, just build/refresh it — it is cheap and deterministic.

- - Never pass a provider key and never run a semantic (non-`--code-only`) build for discovery. Code discovery is always key-free.

- - If the build/refresh fails for any reason, **fall back to step 5** — do not retry in a loop or block the task.

-

- ### 3. Load prior lessons (if present)

-

- If `graphify-out/reflections/LESSONS.md` exists, `Read` it **once, before your first query**. It is a deterministic digest of what past graph-guided work in this repo actually found useful — preferred source nodes, recorded dead ends, and corrections (aggregated with a 30-day half-life and a 2-result corroboration floor, so one-off noise never becomes a lesson). Use it to prefer the nodes it lists and skip the dead ends it names.

-

- - **Bound the cost.** LESSONS is kept small (≈1500 tokens — no larger than a single `--budget 1500` query), so a full read never costs more than one extra query. If it is ever larger, read only its "Preferred / Dead ends / Corrections" sections.

- - Lessons are **hints, not ground truth** — they point; the code still decides (see Honesty rules).

- - Absent file → skip silently. **A discovering agent only *consumes* lessons — never records them mid-query.** Outcomes are recorded by the orchestrating command at a *verified* gate (e.g. `/orc:debug` after the suite passes), not from a guess. If you queried the graph, surface which nodes you relied on so the caller can record the outcome.

-

- ### 4. Query-first

-

- Answer structural questions against the graph instead of grepping the tree. Prefer, in order of specificity:

-

- ```bash

- graphify query "where is auth wired to the database?" --budget 1500 # BFS/DFS traversal; --budget caps answer tokens

- graphify explain "RateLimiter" # what one symbol is and connects to

- graphify path "UserService" "DatabasePool" # shortest path between two concepts

- graphify affected "processRefund" --depth 2 # reverse blast-radius: who calls / what breaks if this changes

- graphify god-nodes --json --top 10 # architectural hubs (degree centrality; JSON out)

- ```

-

- (Or invoke the `/graphify` skill, which wraps the same commands.) Then:

-

- - **Cite `source_location`** from the results and `Read` only those precise files/spans — not whole directories. `affected` prints each impacted node as `- <symbol> [<relation>] <file>:<line>` — read the cited spans.

- - **`--budget` discipline.** Keep query answers capped (`--budget 1500` default). If a query returns noise, *raise the budget or rephrase against the graph's own node/community names* before falling back to grep — don't reflexively abandon the graph.

- - **`affected` / `god-nodes` are leads, not verdicts.** They tell you *where to look* — candidate callers, load-bearing hubs — far faster than grep; they do **not** license a completeness claim. `affected` output does not expose per-edge confidence, and some edges are `INFERRED`, so verify each cited caller by reading it before asserting anything about it. Never state "all callers handled / nothing else affected" from graph output alone — least of all from a graph whose `built_at_commit` ≠ your tree.

-

- ### 5. Fallback (Graphify absent, build/refresh failed, stale, or empty graph)

-

- Use today's discovery path unchanged: `Glob` for candidate files, `Grep` for symbols/usages, `Read` the immediate dependencies. This is the correct behavior whenever Graphify is not usable — it is a graceful degradation, not an error. Say nothing alarming; just proceed.

-

- ### 6. Keep the graph out of version control

-

- Graphify writes to `graphify-out/`. Ensure it is ignored **without** creating a diff in the user's tracked `.gitignore` — use the repo-local exclude file:

-

- ```bash

- grep -qxF 'graphify-out/' .git/info/exclude 2>/dev/null || echo 'graphify-out/' >> .git/info/exclude

- ```

-

- (In a worktree, `.git` is a file pointing at the real gitdir; `git rev-parse --git-path info/exclude` resolves the correct path if you need to be exact.)

- - Never claim you "used the code graph" if you fell back to grep — and vice-versa. State which path you took only if it matters to the answer.

- - Never treat a Graphify answer as ground truth without reading the cited source. The graph points you at code; the code is the source of truth. Lessons (step 3) and `affected` / `god-nodes` leads (step 4) are hints — verify by reading before you assert.

- - **Freshness is load-bearing for any completeness claim.** A stale graph (`built_at_commit` ≠ the reviewed tree) can omit a new caller or list a deleted one — a confident-but-wrong answer is worse than none. Refresh (`graphify update .`) or grep the changed area; never source a "handled every case" claim from a stale graph.

- - **Probe before you trust a new verb.** Graphify is pre-1.0 and its CLI surface moves. If a command errors, exits non-zero, or returns output you can't parse, treat the graph as unavailable for that question and fall back to grep — degrade to a slower answer, never to a wrong one. Keep all graphify calls inside this protocol so a breaking change is fixed in one place.