---
title: Context as Code
description: Treat analytics context like code - version it, review it, merge it.
---

## The idea

dbt moved analytics transformations into git. KTX applies the same pattern to
analytics context: metric definitions, joins, business rules, wiki pages, and
ingest decisions become files that can be reviewed, merged, and audited.

| Before | With KTX |
|--------|----------|
| Context scattered across BI tools, chats, docs, and analyst memory | Context lives in YAML and Markdown |
| Agent changes are hard to inspect | Agent changes are git diffs |
| Imports overwrite local judgment | Ingest reconciles with existing files |
| History depends on tool logs | History lives in commits and transcripts |

## Auto-ingestion

Most context already exists in dbt manifests, LookML, MetricFlow, Metabase,
Notion, warehouse metadata, and analyst notes. KTX reads those inputs through
adapters, then reconciles them into local files.

```text
source tools -> adapters -> reconciliation agent -> YAML + Markdown diffs
```

| Step | What happens | Output |
|------|--------------|--------|
| **Extract** | Adapters read models, metrics, questions, schemas, and docs | Structured metadata |
| **Reconcile** | The agent compares incoming facts with existing context | Create, update, skip, or flag |
| **Write** | KTX saves changed semantic sources and wiki pages | Reviewable project files |

Reconciliation is the key difference from a sync. KTX preserves accepted local
edits, fills gaps, and surfaces conflicts instead of blindly overwriting files.

## The git workflow

Run ingestion on a branch, review the changed YAML and Markdown, then merge the
accepted context the same way you merge dbt or application code.

```text
dbt / BI / docs / warehouse
          |
          v
   ktx ingest --all
          |
          v
 branch: ingest/nightly
          |
          v
   semantic diff in PR
          |
          v
 approve and merge
          |
          v
 agents read updated files
```

Typical review checklist:

- new sources match the warehouse and source-tool evidence;
- joins have the right relationship direction;
- generated measures match business definitions;
- wiki pages capture caveats without duplicating YAML;
- `.ktx/` runtime state stays out of git unless your team intentionally reviews
  a report or transcript.

Teams often run ingestion on demand during setup, then schedule
`ktx ingest --all --no-input` on an ingest branch once the source is stable.

## Feedback loops

Context improves when human corrections and agent signals flow back into the
same reviewed files.

| Signal | Example | Where it lands |
|--------|---------|----------------|
| Analyst correction | A measure excludes test accounts | `semantic-layer/**/*.yaml` |
| Business clarification | ARR changed definition this quarter | `wiki/**/*.md` |
| Agent query issue | A filter returns no rows unexpectedly | Wiki caveat or tighter source filter |
| Join problem | A path duplicates order-level measures | Relationship metadata or grain fix |

Accepted corrections become input to the next ingest run. That makes the
context layer converge toward the team's current source of truth.

## Deterministic replay

Every ingestion session records the adapter inputs, tool calls, LLM responses,
write decisions, and reasoning behind each change.

| Use case | What replay gives you |
|----------|-----------------------|
| **Debugging** | Trace a bad source, join, or measure back to the input that produced it |
| **Trust** | Show where a definition came from and who reviewed the resulting diff |
| **Reproducibility** | Compare old and new ingest behavior after config or model changes |

Commit the YAML and Markdown changes. Commit reports or transcripts only when
they are part of your team's review workflow.

## Agent usage notes

Use this page when an agent needs to explain review workflows, ingestion diffs,
replayability, or why KTX writes YAML and Markdown instead of hiding context in
a hosted service.

| Agent task | Relevant section | Next page |
|------------|------------------|-----------|
| Explain how generated context should be reviewed | The git workflow | [Building Context](/docs/guides/building-context) |
| Diagnose why ingestion changed a semantic source | Auto-ingestion / Deterministic replay | [ktx ingest](/docs/cli-reference/ktx-ingest) |
| Explain how context improves over time | Feedback loops | [Building Context](/docs/guides/building-context) |
| Tell a user what to commit | The git workflow | [Writing Context](/docs/guides/writing-context) |