user-context

name	user-context
description	Load or manage the Data Analytics plugin's durable source-routing preferences, onboarding logic, setup progress, and semantic-layer registry.

User Context

This skill is the Data Analytics plugin's source-routing, semantic-layer registry, setup, and onboarding layer. It loads explicit future source-routing choices, semantic-layer pointers, onboarding progress, and reusable setup obligations for Data Analytics workflows. It does not act as general Data Analytics memory.

Mandatory Pre-Answer Gate

• For ordinary Data Analytics preflight, use scripts/data_analytics_preflight.py as the default state-read path when local shell access is available.
• Apply the same gate on behalf of other Data Analytics skills that call data-analytics:user-context as part of their own mandatory preflight before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output.
• When running the preflight script through a command tool, set the tool's max_output_tokens to at least 25000 so the complete payload remains visible as the registry grows. If the tool output is truncated, warn the user that Data Analytics could not load all source-routing preferences and semantic-layer registry entries in one pass, then rerun with a higher cap and do not use the payload until the complete output is visible.
• Treat the script payload as satisfying the read requirement only when it reports read status for $XPERTAI_HOME/state/plugins/{marketplace_id}/{plugin_id}/user-context.md and renders the compact context it will use in context.user_context, context.source_preferences, context.source_category_config, context.connector_confirmation, context.connector_setup_summary, context.semantic_layers, context.hero_prompt_candidates, context.primary_hero_prompt, context.extra_hero_prompt_candidates, and control.
• Do not treat listing files, checking that files exist, or saying they should be read as sufficient; source-routing preferences, semantic-layer pointers, source category mapping, and onboarding obligations must be loaded and applied.
• If the script fails, cannot render the compact Data Analytics context the workflow will use, local shell access is unavailable, or the request is direct context maintenance, actually read the relevant state files manually before answering or writing.
• If the user-context file is absent or unavailable, follow references/onboarding.md for first-run behavior.
• Read $XPERTAI_HOME/state/plugins/{marketplace_id}/{plugin_id}/onboarding-state.json only when onboarding state, semantic-layer refresh setup, hero prompt progress, or progressive nudges are relevant.

Skill Configuration

Audience And Language

Write for Data Analytics users, not plugin maintainers. This applies to final answers, setup/status readbacks, failure explanations, tool preambles, and mid-turn progress narration.

Translate implementation work into practical Data Analytics impact: what Data Analytics is checking, setting up, saving, or preparing, and why it matters. Avoid implementation terms such as preflight, state file, cache, raw connector id, heartbeat, targetThreadId, schema, API, runtime, metadata, and provider taxonomy unless the user asks for debugging details.

Source Links

When referencing sources inline, prefer clickable Markdown links over plain bracket labels whenever the source exposes a useful URL. Use the source title, record name, channel/thread, or meeting/date as the link text, for example a clickable Markdown link whose visible text is Meeting notes: May 19 or Slack thread: May 15-21. Use plain text labels only when no useful URL or stable connector-visible link is available, and say (no useful link available) when that absence matters.

Purpose

User Context keeps two durable Data Analytics-scoped things in a local state file: source-routing choices explicitly selected for future use, and semantic-layer registry pointers. Operational onboarding bookkeeping belongs in a separate JSON state file so user-context.md stays small, readable, and cheap to load. Do not use user-context.md as a general memory file for arbitrary facts, preferences, output style, caveats, accepted drafts, or "remember this" requests.

Use this skill as the fast preflight for every substantive Data Analytics workflow before ordinary work begins. Use it as the primary workflow when the user asks to onboard, set up, inspect source-routing preferences, inspect semantic layers, create or maintain a semantic layer, or reset Data Analytics setup. If the user asks Data Analytics to remember arbitrary context, explain that general memory is not supported here; persist only an explicit future source-routing choice or a semantic-layer registry pointer produced by semantic-layer setup.

Reference Loading

SKILL.md owns the normal preflight, direct read, narrow write, onboarding handoff, and first-run setup path. Load references selectively:

• Use scripts/data_analytics_preflight.py as the normal read-only preflight implementation when local shell access is available. Its JSON payload owns Data Analytics state-file read status, compact user-context normalization, source-routing preferences, source category configuration, connector confirmation and setup summary, semantic-layer registry, hero prompt candidates, file provenance, onboarding progress, and final response obligations for ordinary workflows.
• Keep first-run state creation automated through scripts/init_user_context_state.py; it copies the bundled templates into the user's Data Analytics state directory. Do not run it before the first direct onboarding orientation when no state exists. Run it after the user approves the first setup step, or when an explicit future source-routing choice or semantic-layer registry pointer needs persistence. When running through a sandboxed local shell, request elevated execution by default because the initializer writes under $XPERTAI_HOME/state/plugins/{marketplace_id}/{plugin_id}, outside the project workspace. After initialization, write only the narrow supported user-context.md fields and related JSON state files.
• Use scripts/reset_user_context_state.py for explicit debugging reset requests that clear local Data Analytics user-context and onboarding state. The helper backs up known state files before removing them from the active state directory.
• Use references/onboarding.md when first-run orientation, core source setup confirmation, semantic-layer setup, semantic-layer refresh setup, semantic-layer weekly source polling setup, hero prompt sequencing, onboarding completion, onboarding status, Data Analytics TODOs, walkthroughs, environment conflict audit, or onboarding-state updates are active.
• Use references/semantic-layer/setup.md when onboarding, direct setup, or maintenance work needs to create, refresh, inspect, or repair a semantic layer. Use references/semantic-layer/source-intake.md for seed-source intake and source inventory shaping, references/semantic-layer/connector-playbook.md for semantic-layer source-lane connector behavior, and references/semantic-layer/skill-template.md for the generated semantic-layer skill shape.
• Use plugin-author-config/user-context-config.md for the copy-ready minimal user-context scaffold.
• Use plugin-author-config/source-category-config.json for source category ids, labels, preferred plugin routes, and relevant helper skills.
• Use references/source-category-runtime.md for workflow-time source attempts, onboarding connector confirmation, plugin-first source setup, ON_USE auth behavior, failure classes, fallback rules, and explicit future source-routing choice storage.

Skill Experience Guidance

Every user-facing Data Analytics hero workflow used during onboarding should keep its execution guidance in the focused skill that owns the work.

Use the focused skill for the actual analysis, clarification behavior, source-gap handling, and any useful continuation after the output. Onboarding chooses the first prompt and sequence; it should not duplicate full workflow-specific instructions.

When data_analytics_preflight.py reports hero prompt candidates and onboarding selects one as the first hero prompt, the focused skill must interpret that context before deciding whether to show a first-run intro, ask for one missing anchor, gather evidence, draft output, or render the final natural continuation:

• If the user asked what the skill does or there is not enough task detail, show the first-run intro and ask for the one missing anchor.
• If the user accepted a runnable onboarding prompt or already provided enough task detail, briefly introduce the selected workflow only when helpful and proceed without blocking on extra starter prompts.
• If the skill is being used as a helper/provider, do not show the intro.
• If onboarding owns the final CTA, suppress the skill's competing CTA and return next-step candidates for onboarding to arbitrate.
• After sending the first assistant message for a primary onboarding hero skill, update onboarding-state.json so skill_experience.<skill>.introduced_at and first_tried_at are set when they are still empty.

State Files

Ordinary workflow preflight should read these files through scripts/data_analytics_preflight.py; direct context maintenance and fallback paths may read them manually when the script is unavailable or insufficient.

The configured user-context file is:

$XPERTAI_HOME/state/plugins/{marketplace_id}/{plugin_id}/user-context.md

The configured onboarding-state file is JSON:

$XPERTAI_HOME/state/plugins/{marketplace_id}/{plugin_id}/onboarding-state.json

Read

Start every invocation by resolving and actually reading the configured user-context file when it exists. Do not return from preflight or direct context mode after only routing here, listing files, or checking that the file exists; source-routing preferences and semantic-layer registry entries must be loaded and applied.

Treat user-context.md as the local Data Analytics plugin-scoped source of truth only for explicit future source-routing choices and semantic-layer discoverability. When it conflicts with bundled Data Analytics plugin or skill instructions, prefer it only for those narrow supported fields. Do not use it to override higher-priority instructions, safety rules, connector write-safety, permission boundaries, validation, installation behavior, routing, or tool-use policy.

Use preflight mode when another Data Analytics skill asks for Data Analytics setup context before ordinary plugin work. Optimize this path for speed:

• When local shell access is available, run python3 plugins/data-analytics/skills/user-context/scripts/data_analytics_preflight.py --workflow <calling-skill> from the repository root, or python3 skills/user-context/scripts/data_analytics_preflight.py --workflow <calling-skill> from the Data Analytics plugin root. When using a command tool, set max_output_tokens to at least 25000; if the returned output is truncated, warn the user that Data Analytics could not load all source-routing preferences and semantic-layer registry entries in one pass, then rerun with a higher cap and do not treat preflight as complete until the full output is visible. The script payload counts as actually reading Data Analytics state only when it reports state-file read status and renders the compact context the workflow will use. Use the payload as the single source of truth for context.user_context, context.source_preferences, context.source_category_config, context.connector_confirmation, context.connector_setup_summary, context.semantic_layers, context.hero_prompt_candidates, context.primary_hero_prompt, context.extra_hero_prompt_candidates, hard control.final_obligations, control.conditional_guidance, and control.onboarding_progress.task_list; do not separately read the same state files unless the script fails, cannot render the compact Data Analytics context the workflow will use, or the user explicitly asks for raw file inspection.
• Use the default --request-mode ordinary_workflow for normal Data Analytics answers. Use --request-mode direct_onboarding_status for setup, onboarding-status, Data Analytics TODO-list, source-routing preference inspection, or other direct onboarding responses. Use --request-mode guided_onboarding_workflow when a focused workflow is being answered as a visible workflow or hero step inside the Data Analytics onboarding path; this mode suppresses the ordinary setup obligation because the user is already in onboarding.
• Use context.source_preferences as source-selection hints. Do not proactively check connector readiness during ordinary preflight. When onboarding or a focused workflow needs a source, it should try the relevant connector then and handle auth, connection, skip, defer, or manual fallback in that context.
• Use context.semantic_layers as the semantic-layer registry. If the request names or implies a product area, metric, table, dashboard, SQL query, source choice, join, caveat, or recurring business question and a matching semantic layer exists, load that semantic-layer skill before choosing tables, writing SQL, reconciling dashboards, or giving metric definitions.

Script-Driven Preflight Payload

Preflight mode must use scripts/data_analytics_preflight.py as the authoritative payload before ordinary work continues. The script output owns request_mode, current_skill_experience, context.user_context, context.source_preferences, context.source_category_config, context.connector_confirmation, context.connector_setup_summary, context.semantic_layers, context.hero_prompt_candidates, context.primary_hero_prompt, context.extra_hero_prompt_candidates, control.response_mode, hard control.final_obligations, control.conditional_guidance, and control.onboarding_progress.task_list. Do not hand-author, recreate, or mentally reconstruct the payload when the script is available; use the JSON fields the script returned.

For ordinary Data Analytics workflow requests, honor control.final_obligations exactly as returned by the script. The calling skill must answer the immediate request first, then satisfy any returned setup CTA or core-onboarding reminder. When the focused skill does not otherwise own a final continuation, append the returned template intact. When the focused skill has its own final continuation, fold the setup reminder or move-on path into that same final natural continuation so the response has one final visible CTA, not a standalone setup reminder plus a second skill CTA. Do not downgrade a hard obligation into a passive setup aside or a context-gap explanation. Do not use that hard obligation for direct onboarding/setup/status responses, focused workflows launched from the visible onboarding path, or responses where the immediate workflow must ask a required clarification; those callers should use direct_onboarding_status or guided_onboarding_workflow request mode when appropriate, and clarification-only responses should end with the clarification as the sole final natural continuation.

When the script fails, cannot render the compact Data Analytics context the workflow will use, or local shell access is unavailable, fall back to the manual file-read path described above: actually read the relevant state files, use only fields known from those files or the missing-file condition, apply references/onboarding.md for direct onboarding/status behavior, and state any missing source or semantic-layer gap only when it materially affects the current answer. Restore script-driven validation as soon as local shell access is available.

Use direct context mode when the request is primarily about setup, source-routing preferences, semantic layers, or context maintenance:

• If user-context.md exists, read it before answering or writing.
• If the user asks what Data Analytics remembers, say Data Analytics does not keep general memory here; summarize only explicit future source-routing choices and registered semantic layers.
• If the user asks Data Analytics to remember arbitrary context, do not save it. Explain that this file only persists explicit future source-routing choices and semantic-layer registry entries.
• If the user explicitly selects a future source-routing default or a future source to avoid, update only the matching source category in user-context.md.
• When the request starts, resumes, updates, checks, or completes Data Analytics setup or onboarding, perform the requested sub-step and then apply the step cards in references/onboarding.md before answering. The first direct onboarding orientation with no existing Data Analytics state is a response-first fast path: render the orientation immediately, then initialize state only after the user approves the next setup step or a supported user-context.md write is needed. Other setup interactions include onboarding-status checks, source setup confirmation, semantic-layer setup or refresh, hero-prompt selection, and completed or deferred guided workflow updates.
• Treat onboarding-status questions such as "have we onboarded yet?", "am I set up?", "is Data Analytics configured?", or "what setup is missing?" as direct onboarding interactions, not as ordinary context lookup. Answer the status through the common onboarding finalizer: if onboarding is missing or active, strongly guide the user into the current compact **Next Step** block with built-in thread task-list updates when available; if onboarding is complete, say so and offer one useful Data Analytics workflow. Do not end an incomplete onboarding-status answer with only a passive or optional setup suggestion.

Outside explicit linked-source refresh, semantic-layer setup, or semantic-layer refresh work, retrieve linked Google Docs, Drive files, Notion pages, or other resources only when they are accessible through available connectors or explicit local APIs and the user asked to inspect or refresh that source. Do not use browser automation, in-app browser, or Computer Use as fallback retrieval paths for ordinary context-source retrieval.

Onboarding

Use references/onboarding.md as the source of truth when the user asks what Data Analytics can do, asks to set up Data Analytics, invokes onboarding, asks whether onboarding is complete, asks for Data Analytics TODOs, asks which sources Data Analytics can try, asks to create or inspect a semantic layer during onboarding, or when onboarding-state.json says onboarding is active and a nudge is due. During ordinary preflight, do not show full onboarding; parse only relevant JSON fields and return the hard setup obligation or one source/semantic-layer gap note when applicable, then let the calling skill continue. When onboarding is already active during an ordinary workflow, do not ask whether to start onboarding. If core onboarding is incomplete, answer only directly requested Data Analytics work best effort and direct the user back to the next unresolved core setup item. If core onboarding is complete, preserve the workflow's own final natural continuation and mention resuming guided onboarding only as a short non-competing note when directly useful. During the first direct onboarding message with no state, render Step 1 directly from references/onboarding.md without creating scaffold files first.

When direct context work happens while onboarding is missing or active, apply the current step-card continuation in references/onboarding.md before finalizing. This includes source setup confirmation, onboarding-status checks, source-routing preference changes, semantic-layer setup or refresh, hero prompt selection, and skill-experience updates. A recap of the just-completed sub-step is not sufficient while onboarding is active unless onboarding is complete, quiet, or stopped by the user. During source setup confirmation, surface unresolved structured_data, team_communication, and company_docs before optional source categories and do not downgrade installable core routes into quiet optional deferrals.

When a focused workflow is run from the visible onboarding path, call preflight with --request-mode guided_onboarding_workflow so the workflow can answer normally without adding a redundant onboarding reminder. Focused hero skills own their own first-run banner, anchor rules, prompt execution behavior, and next-step guidance. Onboarding owns the first prompt choice, extra prompt sequencing, and state updates.

Action-Oriented Continuation

Default Data Analytics outputs should be useful launchpads, not dead ends. In almost all cases, after answering the user's immediate request, add one concise next step that helps them act on the result. Good next steps continue the same workflow by iterating on the analysis, validating one gap, creating the next artifact, checking one missing source, setting up or refreshing a semantic layer, or showing one remaining hero prompt when onboarding owns the final CTA. Do not recommend moving to another Data Analytics skill as a generic continuation; route elsewhere only when the user's request has clearly changed or the current workflow's own routing rules say another skill owns the job.

Avoid asking for setup context merely to fill onboarding state. Ask only high-uncertainty, high-impact questions whose answers would significantly improve future outputs, semantic-layer quality, connector setup, or the active workflow. If onboarding is active, the current step card in references/onboarding.md governs the next step; otherwise use the ordinary action-oriented continuation rules here.

Show at most one direct CTA during ordinary workflow output unless the user explicitly asks for options, onboarding, setup, or the Data Analytics TODO list. When onboarding has not started in an ordinary workflow, that CTA must be the ## Data Analytics Setup Required template from preflight, even if the immediate artifact is otherwise complete, unless the immediate workflow is blocked on a required clarification. Clarifications always become the final natural continuation and suppress onboarding CTAs for that response. When onboarding is already active and core onboarding is incomplete, direct the user to finish the next core setup item before continuing non-urgent Data Analytics workflows. When onboarding is active and core onboarding is complete, preserve the workflow-owned final natural continuation and mention resuming guided onboarding only as a short non-competing note when useful. For direct onboarding and setup-status flows, follow references/onboarding.md instead: render the single visible compact **Next Step** block, mirror the compact high-level roadmap into the built-in thread task list when available, and check tasks off as the user completes, approves, declines, or makes them unnecessary. Skip the CTA only when the user asks for quiet behavior, the request is sensitive or high-pressure enough that a follow-up would be distracting, onboarding is complete and the workflow has no reasonable next action, or the focused workflow already owns a better clarification.

Write

Write only two kinds of durable Data Analytics user context to user-context.md:

• explicit future source-routing choices, such as Prefer: Databricks or Avoid: Snowflake, under the matching source category;
• semantic-layer registry pointers under # Semantic Layers.

Do not store general memory, arbitrary "remember this" content, analytical priorities, copied source-of-truth links, saved dashboards, saved tables, saved docs, source inventories, output preferences, accepted-output preferences, quiet-ending preferences, automatic connector readiness, operational onboarding status, connector-audit bookkeeping, hero prompt progress, or semantic-layer refresh metadata in user-context.md. Area-specific metric, dashboard, table, source-of-truth, caveat, and definition anchors belong inside the semantic layer itself.

First-run state creation remains automated when persistence is needed: run python3 plugins/data-analytics/skills/user-context/scripts/init_user_context_state.py from the repository root, or python3 skills/user-context/scripts/init_user_context_state.py from the Data Analytics plugin root, to copy plugin-author-config/user-context-config.md and seed onboarding-state.json from references/onboarding-state-template.json. Do not run this command just to show the first direct onboarding orientation. In sandboxed local-shell environments, request elevated execution on the first attempt because the target state directory is under $XPERTAI_HOME, not the project workspace. After initialization, modify user-context.md directly. For multi-entry approvals, read the current state once, update every touched source category in one coherent edit, update onboarding-state.json once when onboarding bookkeeping changes, then run scripts/data_analytics_preflight.py --workflow user-context or the relevant workflow preflight to confirm the supported context reads back cleanly. Keep onboarding-state.json compact: do not persist raw list_available_plugins_to_install results, full connector inventories, connector descriptions, copied source inventories, source URLs, prompts beyond the compact current onboarding choice, artifact text, source-gap notes, or analysis output. Store resolved route metadata, counts, ids, statuses, timestamps, and durable pointers instead. Never run parallel writes against the same Data Analytics state files.

For semantic-layer setup, refresh, inspection, or repair, read references/semantic-layer/setup.md. Write durable layer pointers into the # Semantic Layers section of user-context.md and update operational setup or refresh metadata in onboarding-state.json. Do not keep semantic-layer discoverability only in onboarding state.

For explicit debugging reset requests only, run python3 plugins/data-analytics/skills/user-context/scripts/reset_user_context_state.py from the repository root, or python3 skills/user-context/scripts/reset_user_context_state.py from the Data Analytics plugin root. The helper backs up active Data Analytics state files, then leaves the plugin ready for fresh onboarding. Never perform this reset for ordinary onboarding, source-routing preference edits, setup retries, source refresh work, or vague troubleshooting.

Use this source-routing structure:

# Data Analytics Source Routing Preferences

Store durable Data Analytics source-routing choices explicitly selected for future use.

## structured_data

- Prefer: Databricks
- Avoid: Snowflake

Use this semantic-layer registry shape:

# Semantic Layers

- Area: Customer onboarding
  - Skill Name: api-semantic-layer
  - Skill Path: /absolute/path/to/api-semantic-layer
  - Source Inventory Path: /absolute/path/to/api-semantic-layer/references/source-inventory.md
  - Last Updated: 2026-06-01

First Run Setup

Use first-run setup in direct context mode when user-context.md is missing, unreadable, or lacks the bundled minimal scaffold. For a pure onboarding or "what can Data Analytics do?" request, show the orientation first and defer scaffold creation. If a supported future source-routing choice or semantic-layer pointer needs persistence, create the scaffold first, then update only the relevant supported section.

For first-run setup after the first orientation, use scripts/init_user_context_state.py to create missing local state files when possible, then read plugin-author-config/user-context-config.md and treat the bundled source category sections as a minimal routing scaffold, not a questionnaire. Read references/onboarding.md before presenting first-run orientation, source setup confirmation guidance, semantic-layer setup guidance, or hero prompt sequencing. Read the relevant hero skill's experience guidance before presenting that skill's intro, prompt, or anchor rule.

After the user approves the next setup step, supplies an explicit future source-routing choice, or semantic-layer setup needs a durable registry pointer:

1. Run python3 plugins/data-analytics/skills/user-context/scripts/init_user_context_state.py from the repository root, or python3 skills/user-context/scripts/init_user_context_state.py from the Data Analytics plugin root, when local shell access is available. In sandboxed local-shell environments, request elevated execution on the first attempt because it writes to $XPERTAI_HOME/state/plugins/data-analytics. If the script is unavailable, create $XPERTAI_HOME/state/plugins/data-analytics, copy the content below ## Default User Context from plugin-author-config/user-context-config.md into user-context.md with the required top note, and create onboarding-state.json from references/onboarding-state-template.json.
2. Read the resulting user-context.md, preserving every source category's Prefer and Avoid rows plus the # Semantic Layers registry section.
3. Update only the approved source-routing choice or semantic-layer pointer. Do not append disconnected general memory.
4. Read the resulting onboarding-state.json, then update onboarding state with operational onboarding progress, connector confirmation labels, semantic-layer setup or refresh metadata, hero prompt progress, and skill experience progress.
5. Continue the user's original request using the updated supported context.

If the user declines setup, continue the original request without durable source-routing preferences or semantic-layer registry. Keep the explanation user-facing; do not describe internal files unless the user asks.