What you actually do, in order.

Workflow one · about twenty minutes

Understanding a project you've just inherited.

The goal is not to understand the code. It is to know the shape well enough that the next ticket lands somewhere specific instead of nowhere.

1. 01

   Read the domain, not the code

   If the project has an Elevator spec, this is the whole product surface in one screen — categories, the features under them, and the file each one claims. Forty-four lines to replace a week of orientation.

   # Elevator spec format
   # - Indentation = containment (parent → child).
   # - Kinds: e=Extension (optional top-level bundle containing Categories + Concepts; only used when the project has separable extensions/plugins), c=Category (grouping of Features), f=Feature (capability), fu=Functionality (qualified <feature>.<verb>; verb on a Feature), @=Concept (cross-cutting concern referenced by multiple Features), ui=UI Page.
   # - Bracketed edges: [where: ui.X] = entity appears at UI page X; [refs: f.X] = entity cross-references Feature X; [cr: PATH] = code reference (file/folder implementing this entity); [cr.<tag>: PATH] = code reference partitioned by layer (common tags: fe=frontend, be=backend).
   # - [UNRESOLVED] = the named entity has no definition in any parsed file; the reference is a broken link.
   # - `← target` (focus mode only) marks the entity the artifact is centred on.
   # - Trust: structure (hierarchy, references) is analyzer-checked, but descriptions and cr: paths are authored, not derived from code — they can lag recent changes. Treat them as strong leads, not ground truth; verify mechanism details against the cr: target before relying on them.
   # Project map (Elevator)
   > 5 categories, 13 features, 12 functionalities, 1 concepts, 0 ui pages
   
   c agent_tools — The agent-facing surface over the graph: read-only MCP tools pulled on demand, … [cr: src/mcp/]
     f dead_code — Removal candidates as an MCP tool call: fan-in 0, minus the populations for whi… [cr: src/mcp/tools.rs]
     f overview — Domain-level Elevator map (or focus bundle) as an MCP tool call — the onboardin… [cr: src/mcp/tools.rs]
     f push_review — Push mode: nao's structural signal arrives without being asked. Fresh-process c… [cr: src/mcp/push.rs]
       fu pr_report — The CI leg: assess_change rendered as one PR comment, edited in place by marker…
       fu self_review — Quiet-when-clean Stop-hook review: only new smells, cycles, and above-floor com…
   c code_graph — Typed entity/relationship graph built from heterogeneous sources — one parser p… [cr: src/parser/, src/analyzer/, src/graph.rs]
     f metrics — Per-entity complexity and coupling (cyclomatic, cognitive, nesting, fan-in/out,… [cr: src/graph.rs]
     f parse_store — Content-hashed per-file parse cache on disk, and the whole of the incremental m… [cr: src/analyzer/parse_store.rs]
       fu invalidate — Entries are scoped by a generation key derived at build time: build.rs hashes s… [cr: src/analyzer/parse_store.rs]
     f parsers — One parser per language behind the LanguageParser trait, deliberately independe… [cr: src/parser/]
       fu infer_types — Reconstructs receiver types so a method call resolves to Type::method rather th… [refs: f.resolution; cr: src/parser/rust/inference.rs]

   show the remaining 22 lines

   The header is the format legend the tool prints for its consumer — a model reading this cold needs to know that cr: is a code pointer and that descriptions are authored, not derived.

   No spec? Then start one folder down, not at the root. A depth-1 map of nao's root lists 206 files — accurate, and useless as a first read. Pick the folder the README or the build file points at and map that.

2. 02

   Find where it hurts before you find what it does

   Complexity alone tells you which code is ugly. Crossed with git churn it tells you which ugly code is actually costing money — and where the next bug is likely to come from.

   # Hotspots of ./vscode-extension (last 180 days)
   Risk = commits in window × LOC-weighted avg composite score. Renames count as fresh paths.
   
   - [risk 1.00] vscode-extension/src/extension.ts — 16 commits, avg pressure 0.06; worst: function `activate` (L43, loc 0, out 112)
   - [risk 0.24] vscode-extension/src/educatorViewProvider.ts — 8 commits, avg pressure 0.03; worst: method `refresh` (L84, loc 0, in 1, out 8)
   - [risk 0.21] vscode-extension/src/server.ts — 4 commits, avg pressure 0.05; worst: method `start` (L45, loc 0, out 18)
   - [risk 0.15] vscode-extension/src/educatorHoverProvider.ts — 3 commits, avg pressure 0.05; worst: method `provideHover` (L27, loc 0, out 13)
   - [risk 0.08] vscode-extension/src/controlsViewProvider.ts — 3 commits, avg pressure 0.03; worst: method `resolveWebviewView` (L67, loc 0, out 9)
   - [risk 0.06] vscode-extension/src/scopeTreeProvider.ts — 2 commits, avg pressure 0.03; worst: function `fetchIndex` (L340, loc 0, out 10)
   - [risk 0.06] vscode-extension/src/sideViewProvider.ts — 3 commits, avg pressure 0.02; worst: function `fetchScope` (L552, loc 0, out 12)
   - [risk 0.05] vscode-extension/src/educatorProblemsViewProvider.ts — 2 commits, avg pressure 0.03; worst: method `refresh` (L107, loc 0, out 9)
   - [risk 0.04] vscode-extension/src/diffViewProvider.ts — 2 commits, avg pressure 0.02; worst: method `resolveWebviewView` (L33, loc 0, out 9)
   - [risk 0.03] vscode-extension/src/panel.ts — 3 commits, avg pressure 0.01; worst: class `VisualizerPanel` (L162, loc 0, methods 26, in 1)
   … and 2 more files with non-zero risk.

   Risk is commits in the window times LOC-weighted refactor pressure. A gnarly file nobody touches sinks; a moderately complex file edited sixteen times rises. Scoped to one half of the repo here — the tool takes a path, and a narrower ranking is usually the useful one.

3. 03

   Map the folder you were pointed at

   Files, their entities, complexity and coupling per entity — one call instead of opening six files to reconstruct the same picture in your head.

   # Map of ./src/analyzer
   6 files — 5 constant, 1 enum, 128 function, 10 module, 13 struct
   
   ./src/analyzer/dependency_resolver.rs (2 entities)
     struct DependencyResolver (L11, loc 19, methods 13, out 3)
     struct TransitiveDependencyResolver (L470, loc 4, methods 3, out 2)
   ./src/analyzer/file_walker.rs (3 entities)
     function is_test_path (L18, loc 4, cx 2, cog 1, in 1, out 3)
     struct FileWalker (L24, loc 5, methods 5, out 2)
     module tests (L188, loc 0, methods 1)
   ./src/analyzer/lsp_tracer.rs (17 entities)
     struct CallSite (L35, loc 6, in 3)
     constant DEFAULT_TIMEOUT_SECS (L50, loc 0)
     constant IDLE_SECS (L55, loc 0)
     function enabled_by_env (L62, loc 3, cx 2, cog 2, in 1, out 2)
     function resolve_exact_calls (L70, loc 36, cx 5, cog 5, in 1, out 18)
     function run (L110, loc 112, cx 15, cog 25, in 2, out 51)
     enum Encoding (L227, loc 4, in 2)
     function encode_col (L235, loc 9, cx 3, cog 1, in 1, out 5)
     struct LspClient (L249, loc 7, methods 11, out 4)

   show the remaining 39 lines

4. 04

   Ask what's wrong with it

   Smells with remediation hints, then everything ranked by refactor pressure. This is the list you bring to a planning meeting.

   # Quality of ./src/analyzer
   
   ## Smells (1)
   - function `discover_files` — ./src/analyzer/mod.rs:112 (L112, loc 4, cx 1, cog 0, in 1, out 3, ⚠ Feature Envy)
   
   Remediation hints:
   - Feature Envy: Move this method to the type it mostly interacts with, or extract shared logic.
   
   ## Top 10 by refactor pressure
   - [1.40] function `validate_elevator_imports` — ./src/analyzer/mod.rs:335 (L335, loc 111, cx 18, cog 47, in 1, out 42)
   - [1.36] function `run` — ./src/analyzer/lsp_tracer.rs:110 (L110, loc 112, cx 15, cog 25, in 2, out 51)
   - [1.19] function `find_entity_by_name_near` — ./src/analyzer/dependency_resolver.rs:396 (L396, loc 60, cx 18, cog 46, in 4, out 24)
   - [0.98] function `create_branch_entities` — ./src/analyzer/mod.rs:730 (L730, loc 88, cx 9, cog 15, in 1, out 26)
   - [0.96] function `resolve_trait_methods` — ./src/analyzer/dependency_resolver.rs:206 (L206, loc 54, cx 11, cog 26, in 1, out 21)

   show the remaining 7 lines

5. 05

   Now look at it

   Only now — with names you recognise — does the picture pay. Open at landmarks, find the cluster you just read about, then open the level up. Doing this first, at full detail, is the mistake everyone makes once.

   analysing…

   Same ladder in the real tool: scope to a folder in Visual Scopes, set the aggregation to file, then drop to entity once the scope is small enough to read. Try it on a hosted repo →

Workflow three · about three minutes

After the change: leave the trail, then prove it holds.

This is the step teams skip, and the reason onboarding costs what it does. It is also where Elevator meets the documents you already keep: the ADR records why, the spec records what and where, and one line joins them.

1. 01

   Deepen only the branch you touched

   The knowledge is cheap the day you have it and expensive to reconstruct later — but only for the part you actually worked on. Adding depth elsewhere is how a spec becomes a document nobody trusts. One verb, one sentence of mechanism, one code reference.

   f smells {
       d: "God Class, Dispatcher, Feature Envy, Shotgun Surgery, Data Bag —
           derived from metric combinations after they settle."
       cr: "src/graph.rs"
       fu detect
   }

2. 02

   Point the feature at the decision

   If the change was governed by an ADR — or created one — a tagged code reference makes that link checkable. cr.adr: is a convention, not a parser feature; the tag vocabulary is free-form, and that is exactly why it costs nothing to adopt.

   f parsers {
       d: "One parser per language behind the LanguageParser trait."
       cr: "src/parser/"
       cr.adr: "docs/adr/0001-per-language-parsers-stay-independent.md"
   }

3. 03

   Let the tools be the radar

   --check separates errors from hints: broken references must be fixed, while “empty” and “orphan” are a to-deepen list — unfinished is a legitimate permanent state. --drift then verifies the anchors: every code reference resolves, and every identifier named in a description still exists in the file that claims it.

   hint: empty: c educator has no Features
   
   0 error(s), 1 hint(s).

   # Elevator drift report
   > code root: .
   > 29 cr reference(s): 21 resolved, 0 missing — 15 identifier(s) checked in 284 file(s), 0 unanchored
   
   ✓ No drift detected: every cr path resolves and every identifier in `d:` is anchored in the claimed code.

   nao's own spec, clean. The hint above is the honest state of one category nobody has deepened yet — it is reported, not failed.

4. 04

   And when someone deletes the ADR

   The whole point of the join. Retire a decision record without touching the spec and the anchor dangles — reported as an error, exit code 1, the same signal a failing test gives CI. A stale link stops being something a reader has to notice.

   # Elevator drift report
   > code root: .
   > 3 cr reference(s): 2 resolved, 1 missing — 1 identifier(s) checked in 95 file(s), 0 unanchored
   
   ## Missing cr paths (error)
   > The code moved or was removed — fix the `cr:` or retire the entity.
   f parsers
     cr: docs/adr/0007-a-decision-that-was-deleted.md — not found under code root

   Captured by deliberately pointing a spec at an ADR that does not exist. Nothing about this output is written by hand.

The visual lane

Filtering is the whole skill.

A graph view is only useful at the density you can read. The ladder below is the same in the VS Code extension, the browser UI and the demo on this site — go down it one rung at a time, and stop as soon as you can name what you're looking at.

1. Scope before you look. Tick one folder, not the repo. Analysis can stay project-wide — it's the drawing that has to be narrow. In the extension these are two separate panels for exactly this reason.
2. Aggregate up. Start at module or file level: one node per file, edges weighted by how many entity-level edges they stand for. Clusters and bridges are visible here and nowhere else.
3. Drop to entities inside the scope. Now the names mean something, because you know which file they came from.
4. Filter by kind and language. Hide parameters and imports; on a mixed codebase, look at one language at a time.
5. Select, then follow. Selecting a node dims everything that isn't its neighbourhood — which is the visual form of impact.

The demo on this site compresses the first three rungs into one control — Landmarks / Structure / Everything — because a marketing page shouldn't ask you to learn a panel layout first. Try the ladder →