Landmark documents

Some context costs far more to discover than it does to record. A subtle ownership rule, an unexpected engine lifecycle, or the reason a tempting fix failed may take hours of investigation and a large agent context window to reconstruct.

A landmark document preserves that context close to the project, then leaves a short pointer near the implementation that depends on it.

When to create one

Use a landmark for:

• issue-driven design with consequences beyond one edit;
• architectural discoveries that are not obvious from the code;
• difficult bugs whose cause or failed approaches matter;
• integrations with lifecycle, ownership, or ordering traps;
• areas future agents are likely to change incorrectly without background.

Do not create one for routine edits, self-explanatory code, or information already maintained clearly in existing documentation.

What a landmark contains

A useful landmark normally records:

• intent or issue — what problem this area solves;
• current state — what is actually implemented now;
• key files — the shortest path into the relevant code;
• reasoning — why the current design exists;
• flow or ownership model — how state moves through the system;
• traps and failed approaches — what should not be casually repeated;
• verification — how to prove the behaviour still works;
• limitations and next work — known boundaries without pretending they are solved.

The headings should match the subject. The goal is a reliable map, not compliance with a rigid template.

Anchor it near the code

The landmark is only useful if a future agent can find it at the moment it matters. Add a concise comment at the architectural pressure point:

// See Architecture/SequencerBakeLandmark.md for procedural clip ownership context.

The comment does not repeat the explanation. It connects a small local clue to the larger durable record. A future agent searching the source sees the warning before changing the behaviour, while an agent starting from the landmark receives direct paths back into the code.

Why this reduces token burn

Without a landmark, each new session may repeat the same searches, open the same files, infer the same relationships, and rediscover the same failed path. Chat summaries help once, but they are detached from the implementation and often disappear from the next working context.

A landmark turns that investigation into reusable project memory:

Expensive investigation
        ↓
Durable landmark ↔ small source-code pointer
        ↓
Focused reading in future sessions

The saving is not only fewer tokens. It is fewer incorrect changes made while reconstructing an incomplete mental model.

Keeping landmarks trustworthy

Landmarks describe implemented reality, so they must evolve with it. When a change invalidates the document, update it in the same pull request. Record when it was last verified and identify the evidence or source files behind factual claims when the project requires stronger provenance.

If a landmark becomes obsolete, mark what superseded it instead of silently leaving two competing explanations. The next agent must be able to tell which map matches the current terrain.

Frontmatter makes those trust signals machine-readable without burying them in the prose.