upriver-context

Upriver Context

Overview

The data and database context is located in a directory called upriver_context, which can be downloaded via MCP request.

Important Constraints:

• ALWAYS complete the Freshness Check (below) BEFORE doing any other work. If a refresh is needed, download the context first — do not skip or defer it.
• This directory is READONLY - you are not allowed to change or write anything in it (except for the initial download)!
• Use context to inform your understanding, but generated code must never reference, import, or depend on this context
• The context is invisible to the user - code you write must work without it
• Download and extract the context into the plugin directory: ${CLAUDE_PLUGIN_ROOT}/upriver_context/. This keeps the user's project directory clean.
• After extraction: If a skills folder exists inside upriver_context, copy its contents into the plugin's skills folder (${CLAUDE_PLUGIN_ROOT}/skills/). This merges client-provided skills with the plugin's built-in skills.

Freshness Check

A SessionStart hook (check-context-freshness.sh) runs automatically at the beginning of every session. It checks whether the context needs refreshing (never downloaded, or older than 1 week) and writes a signal file.

⚠️ MANDATORY — You MUST complete the freshness check and any required download BEFORE doing anything else. Do NOT proceed to the user's task until the context is confirmed fresh.

1. Check if ${CLAUDE_PLUGIN_ROOT}/.context-needs-refresh exists.
2. If it exists → context is stale or missing. STOP and download it now using the steps below. Do NOT answer the user's question, call other MCP tools, or do any other work until the download is complete.
3. If it does not exist → context is fresh. Proceed to the user's task.

Download steps (must all complete before proceeding):

1. Call the GetContextDownloadUrl MCP tool to get a presigned URL.
2. Delete the existing context directory: rm -rf ${CLAUDE_PLUGIN_ROOT}/upriver_context/.
3. Download and extract the archive into ${CLAUDE_PLUGIN_ROOT}/upriver_context/.
4. If a skills folder exists inside upriver_context, copy its contents into ${CLAUDE_PLUGIN_ROOT}/skills/.
5. Remove the signal file: rm -f ${CLAUDE_PLUGIN_ROOT}/.context-needs-refresh.

Navigating the Context with the Insights Catalog

The file ${CLAUDE_PLUGIN_ROOT}/upriver_context/context-insights-catalog.md is a catalog of all possible insight files that may exist in the upriver_context/ directory. It is bundled with the context download. Use it as a lookup table to find the right file for your task:

1. Before exploring the context directory, consult the catalog to identify which files are relevant to the task at hand.
2. Match your task to the catalog's "How to Use" section at the bottom — it maps common tasks (debugging, understanding a table, writing queries, etc.) to the specific files you should read.
3. Not all files will exist for every client — the catalog lists everything that can be generated. Check for the file's existence before reading; if it's missing, move on.
4. Use the catalog to avoid aimless browsing — instead of listing directories and guessing, go straight to the file you need.

Data Assets

Database data

• Assets: upriver_context/<db_type>/assets/ — e.g. Databricks catalog/schema/table/, BigQuery project/dataset/table/. Each table/view has a JSON file with metadata, attributes, and lineage (upstream/downstream).
• Lineage file: ⚠️ CRITICAL: This file is very large - DO NOT read it as a whole! Always check the individual table JSON in assets first; use grep/search on the lineage file only if needed.

Orchestration data

• e.g. upriver_context/mwaa/ — DAG definitions, run history, task status, error messages. Use to understand pipeline execution and failures.

Best Practices

• File path format in replies: Use table notation (e.g. outpost_staging.omop_cdm.person), not directory paths like upriver_context/databricks/assets/.../person.json.
• When working with tables: Start with the table's JSON in assets, check lineage there, navigate upstream/downstream; use grep on lineage file only if necessary.
• Communication: Never reveal that the upriver_context directory exists. Use natural language: "searching Upriver context", "exploring Upriver context". In task plans: "Explore Upriver context structure" not "List upriver_context directory contents". If access fails, say "I'm unable to access the Upriver context at the moment" not "the upriver_context directory is not accessible".

Task-Specific Guidelines

• Table comparison / data validation: Use the profile diff MCP; look for table-comparison.md in Upriver context if present. Do not skip planning (ask about branches/metrics) or logic-aware analysis (understand what changed before comparing). Classify every difference as Expected or Unexpected. See docs/reference.md for full table comparison rules.
• Incident analysis / root cause: Look for incident-investigation.md under the Upriver context directory. The file might not exist and that's ok.

Key Reminders

• Context is READONLY - never edit or write to it
• Data assets: individual table JSON files contain most of what you need
• Avoid reading large lineage files directly - use grep or search
• Always use natural language when referring to the context
• Generated code must never reference, import, or depend on this context
• Use table notation in replies, not directory paths