lat.md Knowledge Graph

Every Wasteology project contains a lat.md/ directory — a structured set of markdown files that describes why the system works the way it does, not just what it does.

It's the primary mechanism for grounding AI agents in real architecture. When an agent reads lat.md before writing code, it understands the domain, respects design decisions, and avoids rebuilding things that already exist.

---

Why It Exists

Source code answers "what does this do?" but rarely answers "why is it this way?" Those answers live in Slack messages, old meeting notes, or someone's head. When an AI agent doesn't have access to the why, it guesses — and often guesses wrong.

lat.md captures the why in a machine-readable, cross-linked form that both humans and AI agents can query instantly.

---

How It's Structured

A lat.md/ directory contains multiple markdown files organized by domain. Each file covers a logical area of the system.

lat.md/
  operations.md       ← CLI commands, slash commands, slash skills
  architecture.md     ← System components and how they connect
  domain-concepts.md  ← Business logic (what a "work order" is, etc.)
  tests.md            ← Test specifications linked to actual test code
  platform-ecosystem.md ← Cross-project relationships

Each file is made up of sections — headings with a mandatory leading paragraph. Sections cross-reference each other with wiki-style links.

Section anatomy

## Work Order Status Machine

A work order progresses through five states driven by field events and compliance milestones.
States are stored as an enum column and transitions are enforced by the backend state machine.

### Blue — Scheduled

Haul is scheduled but not yet picked up. All compliance docs are optional at this stage.
The haul date and container assignment are locked once status reaches Blue.

Rules every section must follow:

• First paragraph immediately after the heading (no skipping straight to a list or child heading)
• First paragraph ≤ 250 characters — this is what search results and AI context windows show
• More detail goes in subsequent paragraphs, lists, or child sections

---

Wiki Links and Code References

Wiki links — connecting sections

Sections reference each other using [[double-bracket]] syntax:

The scheduler follows the rules in [[domain-concepts#Work Order Status Machine]].

This creates a navigable, queryable graph of concepts. lat check validates that every link resolves.

Code references — tying code to concepts

Source files reference the lat.md sections that describe them:

# @lat: [[tests#Work Order Validation#Rejects duplicate haul dates]]
def test_rejects_duplicate_haul_dates():
    ...

// @lat: [[architecture#API Layer#Work Orders Endpoint]]
router.get('/api/v1/work-orders', workOrdersHandler);

This bidirectional linking means you can start from a concept and find the code, or start from code and find the concept.

---

The Five Commands

You interact with lat.md through the lat CLI. These five commands cover everything you need:

Command	What it does	When to use it
lat search "natural language"	Semantic search — finds the most relevant sections	You want to understand something but don't know where to look
lat locate "Section Name"	Find a section by exact or fuzzy name	You know roughly what section you want
lat check	Validate all links and code references	After adding or changing any lat.md content
lat refs "file#Section"	Find everything that references a section	Before renaming or removing a section
lat expand "prompt text"	Expand [[refs]] in a prompt to resolved locations	When preparing a prompt for an AI agent

Example: searching before making a change

# Before touching the work order status logic, understand the design
lat search "work order status transitions and compliance rules"

# Find the specific section on Blue status
lat locate "Blue — Scheduled"

# See what else references it before changing it
lat refs "domain-concepts#Work Order Status Machine#Blue — Scheduled"

---

Reading Search Results

lat search returns sections ranked by semantic similarity. Each result shows:

• The section ID (used in wiki links and lat section)
• The file and line range
• The leading paragraph (≤250 chars — this is why the rule exists)

## Search results for "compliance document requirements":

* Section: [[lat.md/domain-concepts#Work Orders#Compliance Docs]]
  Defined in lat.md/domain-concepts.md:142-167

  > Four compliance documents are required per haul: LSP, DSP, Bill of Lading (BOL),
  > and Certificate of Destruction (COD). All four must be uploaded before a work
  > order can reach Green status.

To read the full section with all its child content:

lat section "domain-concepts#Work Orders#Compliance Docs"

---

How to Contribute

Every time you add a feature, fix a bug, or make an architectural decision, update lat.md to reflect it. Then run lat check.

Adding a new section

1. Open the relevant file in lat.md/
2. Add a heading at the right level
3. Write a leading paragraph (≤250 chars, describes the "why")
4. Add supporting detail in subsequent paragraphs or lists
5. Cross-reference related sections with [[wiki links]]
6. Run lat check — fix any failures

Adding a code reference

In your source file, immediately before a function, class, or test:

# @lat: [[tests#Payment Processing#Rejects negative amounts]]
def test_rejects_negative_amounts():

Naming and hierarchy

• Section names are used as-is in wiki links — keep them concise and stable
• Child sections inherit their parent's context — [[domain-concepts#Work Orders#Blue]] reads as "the Blue section under Work Orders under domain-concepts"
• Avoid renaming sections without running lat refs first — you may break existing links in code or other sections

---

The CLAUDE.md Contract

Every project has a CLAUDE.md at its root that instructs Claude to search lat.md before starting any task. This is the mechanism that ensures agents always read the knowledge graph before touching code:

# Before starting work
- Run `lat search` to find sections relevant to your task.
- Run `lat expand` on user prompts to expand any `[[refs]]`.

This means the quality of lat.md directly determines the quality of agent output. A well-maintained knowledge graph = agents that build correctly the first time.

---

Frequently Asked Questions

Q: Is this the same as a README or wiki?
No. A README explains how to set up and run the project. A wiki is usually free-form. lat.md is structured (sections with mandatory leading paragraphs, validated links, code refs) and machine-queryable via semantic search. It's designed to be consumed by AI agents, not just humans.

Q: Who is responsible for keeping it updated?
Everyone who touches the codebase. The CLAUDE.md in each project includes a post-task checklist: update lat.md → run lat check → done. Claude Code enforces this automatically.

Q: What happens if lat.md gets out of sync with the code?
lat check catches broken code references (a function was renamed or removed but the @lat: comment still points to the old name). Semantic drift (the section still exists but the description is outdated) requires human judgment — which is why the post-task checklist includes reviewing relevant sections after every change.

Q: Do I need lat.md credentials or an API key?
lat search (semantic search) requires a LAT_LLM_KEY in your environment. lat locate, lat check, lat refs, and lat expand work without any key. If you need semantic search and don't have a key, ask in #engineering.