Setup

Skill: /setup

Run a 4-phase conversational interview that populates the knowledge system from the user's real context. Turns a blank .knowledge/ directory into a fully configured analytical environment.

Write each phase's files as soon as its answers are in; the summaries below are displayed after the files exist.

Parameters

• No arguments: Start from Phase 1 (or resume from last incomplete phase)
• /setup status: Show current setup state
• /setup reset: Reset profile and preferences (Tier 1)
• /setup reset everything: Full reset including dataset connections (Tier 2)

Trigger Phrases

• /setup
• set up my environment
• configure the analyst
• onboard me

Design Principles

1. Conversational, not interrogative. You are a colleague getting to know someone, not a form engine. Use natural language, react to answers, and weave context forward ("Got it — as a PM on a marketplace team, you probably care about GMV and take rate. Let me ask about your data next.").
2. 2-3 questions at a time, max. Never dump a wall of questions. Group them thematically, ask 2-3, then STOP and wait for a response before continuing.
3. Validate responses. If a role sounds unusual or a path does not exist, confirm before recording. ("You said your CSV directory is data/sales/. I do not see that directory — did you mean data/?")
4. Allow skipping. Mark optional fields clearly. If the user says "skip" or "I'll do this later", record null and move on. Never block progress on optional fields.
5. Show progress. After each phase, display the exact summary format specified.

State File

All setup state lives in .knowledge/setup-state.yaml. Create it on first run if it does not exist.

Schema

# .knowledge/setup-state.yaml
setup_version: 1
started_at: "YYYY-MM-DDTHH:MM:SS"
last_updated: "YYYY-MM-DDTHH:MM:SS"
status: "complete" | "partial" | "in-progress"

phases:
  role_and_team:
    status: "complete" | "skipped" | "pending"
    completed_at: "YYYY-MM-DDTHH:MM:SS" | null
  data_connection:
    status: "complete" | "partial" | "skipped" | "pending"
    completed_at: "YYYY-MM-DDTHH:MM:SS" | null
    partial_reason: null | "warehouse_mcp_needed"
  business_context:
    status: "complete" | "skipped" | "pending"
    completed_at: "YYYY-MM-DDTHH:MM:SS" | null
  preferences:
    status: "complete" | "skipped" | "pending"
    completed_at: "YYYY-MM-DDTHH:MM:SS" | null

Phase 1: Role & Team

Goal: Understand who the user is so we can adapt communication style, technical depth, and default output formats.

Questions

Step 0: Health check (before any questions)

Run the system health check first so setup starts from facts, not assumptions:

from helpers.pipeline.health_check import run_health_check
report = run_health_check()   # setup state, knowledge integrity, data connectivity, helper imports

Summarize the report in three lines (what is configured, what is missing, what is broken). If a helper import fails, stop and fix the environment (pip install -e ".[dev]") before continuing. If setup state shows a partial previous run, offer to resume it instead of starting over.

Ask Group 1, then wait for the answer before Group 2.

Group 1 (ask these now, then wait):

1. "What's your role? (e.g., Product Manager, Data Scientist, Engineer, Marketing Analyst, exec)"
2. "How technical are you with data? Pick the one that fits best:
   • Beginner — I look at dashboards but rarely write queries
   • Intermediate — I can write SQL and read basic stats
   • Advanced — I build models, write complex SQL, and review pipelines"

Group 2 (ask AFTER Group 1 response): 3. "What team or department are you on?" (optional) 4. "What domain does your product operate in? (e.g., e-commerce, SaaS, fintech, marketplace, healthcare, media)" (optional)

Validation

• If role is empty or unrecognizable, ask once for clarification.
• Map common synonyms: "PM" -> Product Manager, "DS" -> Data Scientist, "analyst" -> Analyst, "eng" -> Engineer.
• Technical level must resolve to one of: beginner, intermediate, advanced.

File Creation (Execute Now)

After collecting all Phase 1 responses:

Step 1: Create the user directory if it doesn't exist:

mkdir -p .knowledge/user

Step 2: Use the Write tool to create .knowledge/user/profile.md with this exact structure:

# User Profile

## Role & Expertise

- **Role:** {role}
- **Technical level:** {technical_level}
- **SQL comfort:** {inferred from technical_level: none for beginner, basic for intermediate, intermediate/advanced for advanced}
- **Statistics comfort:** {inferred: none for beginner, basic for intermediate, intermediate/advanced for advanced}
- **Domain:** {domain or "not specified"}
- **Team:** {team or "not specified"}

## Communication Preferences

_Set in Phase 4._

## Corrections Log

<!-- Format: YYYY-MM-DD | What was wrong | What was right -->

Replace {role}, {technical_level}, etc. with actual values from the user's responses.

Step 3: Update .knowledge/setup-state.yaml:

If the file doesn't exist yet, use Write tool to create it with:

setup_version: 1
started_at: "{current timestamp in YYYY-MM-DDTHH:MM:SS format}"
last_updated: "{current timestamp}"
status: "in-progress"

phases:
  role_and_team:
    status: "complete"
    completed_at: "{current timestamp}"
  data_connection:
    status: "pending"
    completed_at: null
  business_context:
    status: "pending"
    completed_at: null
  preferences:
    status: "pending"
    completed_at: null

If it already exists, use Edit tool to set:

• phases.role_and_team.status: complete
• phases.role_and_team.completed_at: "{current timestamp}"
• last_updated: "{current timestamp}"

Step 4 - CHECKPOINT: Verify the files were created successfully by using Read tool on .knowledge/user/profile.md. If it doesn't exist, something went wrong. Fix it before proceeding.

Phase 1 Summary (Display Now)

After all files are created, display this exact format:

✓ Phase 1 complete — Role & Team

  Role:       {role}
  Tech level: {technical_level}
  Domain:     {domain or "not specified"}
  Team:       {team or "not specified"}

Next up: Phase 2 — Data Connection

Then proceed to Phase 2.

Phase 2: Data Connection

Goal: Get the user's data connected so analyses can run.

Questions (2 at a time max)

Group 1 (ask now, then wait):

1. "Let's connect your data. What do you have?
   • CSV files in a local directory
   • DuckDB database file
   • Cloud warehouse (Snowflake, BigQuery, Postgres, Databricks)
   • Nothing yet — I want to use a sample dataset"

Branch Logic

The user's answer to Group 1 determines what happens next.

If CSV:

• Ask: "What's the path to your CSV directory? (relative to this repo root)"
• Use Glob tool to verify the directory exists and list .csv files.
• If directory not found, use Bash tool to check data/ and data/examples/ directories, then suggest alternatives.
• If path is confirmed, invoke the Connect Data skill: use the Skill tool with skill: "connect-data" and args: "type=csv path={the_path}".
• The Connect Data skill will handle creating dataset brain, profiling schema, updating active.yaml.
• After Connect Data returns, check if .knowledge/datasets/{dataset_name}/manifest.yaml exists to confirm success.

If DuckDB:

• Ask: "What's the path to your .duckdb file?"
• Use Read or Bash tool to verify the file exists.
• If confirmed, invoke Connect Data: skill: "connect-data", args: "type=duckdb path={the_path}".
• Check for manifest.yaml to confirm success.

If Cloud warehouse:

• Explain: "Cloud warehouses connect via MCP (Model Context Protocol). This requires configuring .claude/mcp.json with your credentials."
• Invoke Connect Data: skill: "connect-data", args: "type={warehouse_type}" (warehouse_type = snowflake, bigquery, postgres, databricks, redshift, mssql, or mysql).
• Connect Data will guide the MCP setup.
• After Connect Data returns, check its status. If it says "MCP configuration needed", mark Phase 2 as partial.
• Do not block Phase 3. Continue the interview even if warehouse setup is incomplete.

If Nothing yet / sample dataset:

• Use Bash tool to list directories in data/examples/: ls -la data/examples/
• Show brief descriptions if available (check for README files).
• If user picks one, invoke Connect Data with the sample dataset path.
• If user wants to skip: mark phase as skipped in next step.

State Update (Execute Now)

After data connection attempt:

Use Edit tool on .knowledge/setup-state.yaml to set:

• phases.data_connection.status:
  • "complete" if manifest.yaml exists for the connected dataset
  • "partial" if warehouse MCP setup is pending
  • "skipped" if user chose to skip
• phases.data_connection.completed_at: current timestamp (or null if skipped)
• phases.data_connection.partial_reason: "warehouse_mcp_needed" if partial, otherwise null
• last_updated: current timestamp

Phase 2 Summary (Display Now)

✓ Phase 2 complete — Data Connection

  Source:     {type} ({path or "pending MCP setup"})
  Tables:     {N} tables found  (or "N/A — skipped")
  Status:     {connected | partial — warehouse setup needed | skipped}

Next up: Phase 3 — Business Context

Then proceed to Phase 3 (even if data connection is partial or skipped).

Phase 3: Business Context

Goal: Understand the business so analyses produce relevant insights, not just numbers.

Questions (ask in groups of 2, wait between groups)

Group 1 (ask now, then STOP):

1. "What does your company/product do? Just a sentence or two is fine."
2. "What are the 2-3 metrics your team cares about most? (e.g., conversion rate, MRR, DAU, retention, NPS)"

Group 2 (ask after Group 1 response, optional): 3. "What business question or problem are you trying to answer right now? This helps me prioritize what to explore first." (optional — user can skip) 4. "Are there any current OKRs or goals I should know about?" (optional)

Group 3 (ask only if domain warrants it, optional): 5. "Any key segments I should know about? (e.g., free vs paid users, regions, platforms)" (optional) 6. "Is there seasonality or known patterns in your data? (e.g., holiday spikes, end-of-quarter effects)" (optional)

Validation

• Metrics: normalize common names ("CVR" -> "conversion rate", "rev" -> "revenue"). If a metric is ambiguous, ask for a brief definition.
• Business question: if provided, note it for future use. Do NOT run Question Router here — just capture the text.

File Creation (Execute Now)

Step 1: Use Write tool to create .knowledge/user/business-context.md:

# Business Context

## Company & Product

{company_description from Group 1 Q1}

## Key Metrics

| Metric | Definition | Notes |
|--------|-----------|-------|
| {metric_1 from Group 1 Q2} | {definition if user provided one, otherwise "TBD"} | |
| {metric_2 from Group 1 Q2} | {definition if provided, otherwise "TBD"} | |
| {metric_3 if provided} | {definition if provided, otherwise "TBD"} | |

## Current Focus

- **Primary question:** {business_question from Group 2 Q3, or "Not specified"}
- **OKRs/Goals:** {okrs from Group 2 Q4, or "Not specified"}

## Segments & Patterns

- **Key segments:** {segments from Group 3 Q5, or "Not specified"}
- **Seasonality:** {seasonality from Group 3 Q6, or "Not specified"}

Step 2 (Optional - only if dataset is connected AND user provided metrics):

If Phase 2 status is "complete" (not skipped or partial), AND the user provided metrics in Group 1 Q2:

• Read .knowledge/active.yaml to get the active dataset name
• Check if .knowledge/datasets/{active}/metrics/index.yaml exists
• If it doesn't exist, create it with stub entries for each metric:

metrics:
  - name: "{metric_1}"
    definition: ""
    sql: ""

  - name: "{metric_2}"
    definition: ""
    sql: ""

If it already exists, skip this step (don't overwrite existing metrics).

Step 3: Use Edit tool on .knowledge/setup-state.yaml to set:

• phases.business_context.status: complete
• phases.business_context.completed_at: "{current timestamp}"
• last_updated: "{current timestamp}"

Step 4 - CHECKPOINT: Use Read tool to verify .knowledge/user/business-context.md exists and contains the user's responses.

Phase 3 Summary (Display Now)

✓ Phase 3 complete — Business Context

  Product:    {one-line summary from company_description}
  Key metrics: {metric_1}, {metric_2}, {metric_3 if provided}
  Focus:      {business_question or "General exploration"}

Next up: Phase 4 — Preferences

Then proceed to Phase 4.

Phase 4: Preferences

Goal: Configure output style and communication preferences so results match what the user actually wants.