Answers for 30+ Teammates

Undocumented knowledge charges interest.

Technical debt is work a team postpones in software. Knowledge debt is the same pattern in understanding. A rule exists, but only in someone’s head. Skip writing it down and you “save” an hour today. You pay it back every time a person asks, forgets, leaves, or builds on the wrong assumption.

The cost grows faster than headcount. Ten new humans are not just ten onboarding talks. They create more handoffs between analysts, engineers, managers, and agents. Each handoff can change the wording or drop a caveat. A table may be called “latest” while still keeping several rows per post. A campaign view may look additive while repeating the same post across campaigns. Word of mouth almost never preserves those details cleanly.

The hidden cost is decision delay.

The visible cost is time spent answering questions. The larger cost is that work stalls until an answer arrives. An analyst waits before building a report. An engineer avoids changing a table because the consumers are unclear. A new hire picks a familiar-looking source and learns weeks later that it had the wrong grain. Documentation moves common decisions closer to the person doing the work.

Treat documentation as a product.

A product has users, jobs, navigation, ownership, and maintenance. Documentation needs the same things. A folder full of schema exports is not a product. It has facts, but it does not help a reader decide where to begin or what to do next.

Atlas serves three jobs. A new person needs a guided path through the system. An active analyst needs a fast answer such as “Which table should I query?” An engineer or agent needs exact object names, fields, relationships, SQL, and caveats. The same repository supports all three. Each reader just enters at a different door.

Start with a decision, not a catalog.

A new reader does not need 13,853 field names on day one. They need to know that one table keeps history, another keeps the latest post, and another expands posts across campaigns. Atlas opens with that simple model. The full dictionary is there when the question needs it. Good documentation reveals detail in the order humans can use it.

Use machines for coverage and humans for meaning.

Warehouse documentation has two jobs. The first is a census: list every object, field, type, row count, location, and update time. Machines are good at that because metadata is structured and changes often. The second is interpretation: why a table exists, what one row means, which source wins, where duplication enters, and when a metric should not be used. That work needs domain judgment.

Atlas keeps both layers. Snapshot scripts build full inventories from Snowflake and BigQuery metadata. Those generated references cover 343 Snowflake objects with 10,237 fields and 123 BigQuery objects with 3,616 fields — 466 objects and 13,853 physical field records in total. Curated guides sit above the inventory and explain what humans must understand before they query.

Why a schema dump is not enough

A schema can say that campaign_key is a number. It cannot say that it identifies campaign membership, that a post may belong to several campaigns, or that adding campaign-expanded metrics across campaigns can double-count the post. The field list is accurate and still incomplete. Meaning only appears when someone records grain, business rules, and failure modes next to the physical shape.

Why hand-written inventories fail

Manually copying thousands of fields into a document creates instant drift. A new column appears in the warehouse but not on the page. A table is rebuilt and the row count stays old. Atlas generates the broad inventory from metadata, then saves human effort for the parts a query cannot infer. Coverage stays large without asking one person to retype the warehouse.

Give every kind of knowledge one home.

Documentation becomes hard to trust when the same rule lives in many places. One page says a table is daily, another says it is latest, and an old slide says something else. Atlas uses one owner per rule. Other pages link to that owner instead of copying the explanation. A change can be made once and reviewed in one commit.

The repository is shallow on purpose. Foundations explain shared words and mental models. Reporting guides explain the main serving layer and safe query choices. Object folders pair source SQL with handoff notes. Reference pages hold inventories, dictionaries, source maps, and standard queries. Cortex files hold semantic models, custom instructions, and verified questions for AI.

Navigation is part of correctness.

A correct answer buried in an unknown folder does not help a new person. The README has two routes: a learning path for readers starting from zero, and a question-based lookup for humans already working. “Which object should I query?” goes to the serving guide. “Why do the same metrics disagree?” goes to metric nuances. “Where does duplication enter?” goes to lineage. The links encode how an expert would point someone next.

Document changes in meaning, not only movement.

Data lineage is often drawn as arrows between tables. That is useful, but an arrow alone only says that data moved. A reader also needs to know what changed along the way. Did the grain move from daily observations to one latest row? Did a bridge expand one post into several campaign memberships? Did an estimate replace a missing Story metric? Those changes decide whether a downstream number is safe.

Atlas records the full path from BigQuery source tables through Snowflake helpers to historical, latest, and campaign-expanded reporting surfaces. Beside the dependency tree, it names the grain at each step. It marks where estimated values enter, where source priority changes, where campaign scope is applied, and where a join can create duplication.

A contract turns a table into a promise.

Each important object needs a compact contract: full name, owner, grain, key, field meaning, upstream sources, downstream users, refresh behavior, safe metrics, and known limits. That is more than a description. It gives producers and consumers a shared promise. When the object changes, reviewers can ask whether the promise still holds.

Version control makes knowledge reviewable.

A shared doc can be easy to edit and hard to audit. Git records each change as a commit. Reviewers can see who changed a rule, when it changed, and which lines moved. Documentation can change in the same workflow as SQL and semantic models, so code and explanation do not need separate release histories.

The Atlas history contains 89 commits from April 15 through July 31, 2026. All 89 are mine. Work appears across 17 active commit days, with 37 commits in July as the reporting model and AI layer expanded. That history proves sustained authorship and change. It does not prove that every line was correct on every date.

Freshness must be visible.

A stale page can be worse than no page because it looks authoritative. Atlas puts snapshot dates and runtime-check dates near generated inventories and major guides. Object profiles record live row counts, field counts, and last-changed times. When a reader sees an old date, they know to confirm the warehouse instead of treating the page as timeless truth.

Maintenance needs a repeatable loop.

1. Detect changeCompare live metadata with the stored inventory and review new or rebuilt objects.
2. Update the contractChange grain, lineage, ownership, metric, or caveat notes when behavior changes.
3. Update the sourceKeep mirrored SQL and semantic files aligned with the live object.
4. Review the diffUse the commit to inspect exactly what knowledge changed and why.
5. Rebuild the bundleGenerate the agent-readable Atlas from the current repository files.
6. Teach from useTurn repeated questions and mistakes into better navigation, examples, or caveats.

Agents need the same map in a different package.

An AI agent can search many files, but it still needs complete, ordered context. Atlas includes a small Python builder that reads repository files, sorts them by topic and file type, wraps each file in a labeled code block, and writes one generated ATLAS.md. The current bundle contains 119 source files.

That single artifact includes the learning guides, object notes, SQL, semantic YAML, verified queries, and build scripts. A person browses the GitHub folders. An agent can ingest or search the bundle without guessing which documents form the current knowledge base. Both paths come from the same source, so the team does not maintain a separate “AI version” of the truth.

Packaging context does not guarantee good reasoning.

An agent can still miss a caveat, choose the wrong page, or answer beyond the documentation. The bundle improves access; it does not make the model infallible. High-risk work still needs narrow tools, governed data models, verified queries, and visible SQL. Documentation tells the agent how the system works. Other controls decide what it is allowed to do.