Skip to main content

Module 2: The Knowledge Graph (lat.md)

Every Wasteology repo you'll work in carries a lat.md/ directory. It looks like plain markdown, and it mostly is — but treating it as "just docs" misses the point. This module gives you enough to be productive with it from your first day; if you go on to work with Claude Code agents, the ADW Track's lat.md module goes further into the reinforcement loop and the company-wide knowledge atlas.

Why this exists​

New engineers (and AI agents, for that matter) ground themselves in whatever context they can find: comments, old design docs, a senior engineer's memory. All three drift out of date the moment the code changes without a matching update — and nobody notices until someone acts on the stale version. lat.md exists to give both humans and agents a single, structured, cross-linked place that describes what a project does and why, and to mechanically catch the moment it stops matching reality.

Reading a repo's lat.md​

A lat.md/ directory is organized into sections — headings and subheadings, each required to open with a short overview paragraph before any child content. A section is addressed by combining its file and heading path, for example:

lat.md/operations#Execution runtime & the two ADW models

That precision — pointing at one section instead of "somewhere in this file" — is what lets sections and tooling reference each other exactly.

Inside a lat.md/ file, sections link to each other with double-bracket wiki links:

See [[architecture#Content-as-code model]] for how tracks are structured.
You will never write this syntax outside lat.md/

Double-bracket wiki links are valid only inside a project's own lat.md/ files. You'll see them if you open a lat.md/*.md file directly, but you will never write [[like this]] in a normal document, PR description, or chat message — it means nothing outside that context.

The five commands​

You don't need to memorize lat.md's internals to get value from it — you need these five commands:

lat search "natural language query"   # semantic search across all sections
lat locate "Section Name"             # find a section by name (exact/fuzzy)
lat check                             # validate all wiki links and code refs
lat refs "file#Section"               # find what references a section
lat expand "some prompt text"         # resolve [[refs]] inside a prompt

In practice, day to day, you'll reach for two of these constantly:

  • lat search — before starting a task, ask it what the project already says about the area you're about to touch. This is how you avoid reinventing (or contradicting) an existing design decision.
  • lat locate — once you know roughly what a section is called, jump straight to it.

lat check is the one that matters even if you never run it by hand: it's wired into CI as a required check on most Wasteology repos, so a pull request that breaks a documented link or reference simply cannot merge. You'll see this again in Module 3 when we cover branch policy.

Semantic search needs a key

lat search does embedding-based semantic search, which requires an LLM key configured in your environment. If one isn't set up yet, lat locate still works for direct name-based lookups — ask your onboarding buddy about key setup if you need full search working.

Why "grounding" matters beyond just you​

The same lat search / lat check loop that keeps you oriented is what keeps AI coding agents oriented too. When Claude Code (or any agent) is about to work in a repo, reading the relevant lat.md sections first is what stops it from guessing at intent from possibly-stale code comments. If you go on to the ADW Track, you'll see this same mechanism from the agent's side — it's the same knowledge graph, just read by a different consumer.

Wastey says

A repo's own lat.md describes that repo. A separate portfolio-wide atlas aggregates every registered repo's graph into one cross-repo graph — that's deeper detail than you need for onboarding, but it's why keeping your repo's lat.md accurate isn't just a courtesy to your own team.

Hands-on lab​

Pick a real Wasteology repo you have access to (the same one from Module 1's lab works fine).

  1. From that repo's root, run: 
    lat search "<something relevant to a task you're about to do, or just curious about>"
    Read the top result's section. Does it change what you'd have assumed?
  2. Run lat locate "<a section name you already know or can guess>" and confirm it resolves to a file and heading that makes sense.
  3. Run lat check and read the output. If it passes, great — that's the expected state on main. If you're on a branch mid-change and it fails, read the specific error; it names a broken link or missing code reference, not a vague failure.
  4. Open one lat.md/*.md file in an editor and find a [[wiki link]]. Follow it manually to the file and heading it points to, so you've seen a resolved cross-reference with your own eyes at least once.

For a condensed reference once you've got the hang of this, see the lat.md quick-start in the Company Docs.

Explore the five commands​

Click each command to see when and why you'd reach for it.

The five lat commandsInteractive

Click any step to see what happens and who's responsible.

Practice: run the required check​

repo root — offline, no LLM key needed
$ lat check▋

Knowledge check​

What problem does lat.md primarily solve?
Which two lat commands will you use most often in day-to-day work?
Where is double-bracket [[wiki link]] syntax valid?

Next up: Module 3 — Git and ADO.