Most entity pages for undocumented code were empty — a name, a diagram, nothing
else. RFC 0088 asks an LLM to describe what a module or function actually does, grounded in its
real compiled structure or real source text, persists the answer to the ledger at
commit time, and — when a human comment already exists — flags a real
discrepancy instead of trusting it blindly. Verified end to end against a real local model, zero
API cost. That live run found two real bugs a passing test suite hadn't; both fixed the same
session.
RFC 0087 already surfaces a real ////@moduledoc/docstring/JSDoc comment when
one exists — real, but honest about doing nothing when it doesn't, which is most real code
in most real codebases. And even where a comment does exist, it can be stale, wrong, or
incomplete — RFC 0087 can only surface what a comment claims, never check it against
what the code actually does.
# try_fetch (RustSymbol) ## Definition _Not documented in source._ ## Properties _No compiled properties._ // no relationships, no diagram // worth drawing either
The obvious design — a new CompilerPass writing ai_overview onto the same
object id an earlier pass already created — would have been actively dangerous. merge_graphs/build_ckm never dedupe objects sharing
an id across two passes, and each ledger version is a complete snapshot, not a
diff. A bare partial object could become the new "current" version and silently regress every
real structural property (kind, arity, RFC
0087's own description) another pass already wrote.
commit, the same architectural slot commit_rollups/commit_data_lineage already occupy — reads the real current object, clones it, adds properties to that clone, re-appends the clone.ekos ask's citation validation — every prompt is built entirely from real, already-compiled data, nothing speculatively retrieved, so there's no "cited something it wasn't shown" risk to guard against.# hash (ElixirSymbol) ## Definition _Not documented in source._ ## AI-Assisted Overview A function that takes a password as input and returns the hashed version of it, using the Bcrypt library. ## Evidence - ai_overview grounded in hash's own real source lines
Real source, sliced by a new compiled source_span
(Rust via syn's joined spans, Elixir via the existing block-depth
stack), redacted through RFC 0043's baseline before it ever reaches a provider. When a real
human comment already exists, ai_comment_check answers
consistent/stale/incomplete — a real, visible callout on the Definition section, never a
silent overwrite of the real extracted comment text.
A real, deliberately small subsystem — lib/plausible/auth, 15 files — kept a real end-to-end run to minutes on a
free local model instead of the multi-hour real cost the full 900-module backend would take.
Plausible.Auth.Password's real page: "responsible for performing
password-related calculations and checks... hashing, and matching passwords" — grounded, not
guessed, and devlog_90's own identity-resolution fix still holds (exactly 3 real relationships,
no phantom edges).
| Symptom, first real run | Real root cause |
|---|---|
| "116 skipped without a source span" | Compiled CKM genuinely had real source_span data on all of them — checked directly, not assumed |
File.name == "password.ex" | Real path relative to its own [observe] paths entry, not cwd — the real lib/plausible/auth/ prefix silently dropped |
| Fixed: real_file_path + a corrected project_key condition | base != cwd replaces counting [observe] paths entries — still empty for the common paths = ["."] case, now also correct for one scoped subdirectory |
The real analytics backend's own config never triggered this — it lists eight
separate observe path entries. Only a smaller, more targeted real scope (exactly what a "small
piece of backend architecture" test asked for) exercised the single-entry shape. A second,
separate live-found bug: this session's own new Ollama provider selection silently ignored
[llm].model, inherited from a pre-existing gap two other files still
have — flagged, fixed only where new code introduced it.
| Before | After |
|---|---|
multi-target alias X.{A, B} → one phantom edge to the bare shared prefix, never defmodule'd anywhere | real per-leaf edges — a lookahead pre-scan handles mix format's own one-leaf-per-line wrapping |
| "no crate directory matched" on every non-Rust workspace | real compiled Rollup fallback — 5 real subsystems, clearly labeled |
| System Decomposition: aggregate counts only | new Layer Breakdown — priv correctly split, 291 real backend files + 1 real frontend asset |
The exact page this whole effort's own multi-alias fix targeted —
PlausibleWeb.Live.CustomerSupport.Team — now lists all 7 real dependent
modules by name instead of one phantom object with no file, no properties, and no real
relationships of its own.
| Real, shipped | Deliberately deferred |
|---|---|
Module/subsystem/symbol overviews, Rust + Elixir source_span | JS source_span — same pattern, not yet wired (Python fixed the same day, devlog_98) |
ai_comment_check — stale comments flagged, never silently trusted | Per-symbol re-verification against real code regardless of scope size — a materially larger, separately-scoped ask |
| Project-level Purpose/Architecture-style, honestly blank with no README to ground it | Risk KIR kind + real ## Major risks |
Cost-gated (ekos commit --yes), opt-in, same UX --prose established | Real Architecture confidence from an LLM judgment, not just the deterministic evaluator |
Nothing in the right column is a bug hidden from this deck — every one is named, scoped, and reasoned about in its own RFC or devlog.
$ ekos commit --yes # shows a real call-count estimate first # [llm-description] in ekos.toml enabled = true scope = "modules" # cheaper default — "all" also covers symbols
| Full workspace gate | Result |
|---|---|
cargo build/test/clippy -D warnings/fmt --check | Clean, every fix |
| New tests this effort | 30+ new tests — 17 for the LLM-description pass alone, each against real fixtures or a real bug found live |