@overscore/cli 0.11.6 → 0.11.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overscore/cli",
-  "version": "0.11.6",
+  "version": "0.11.7",
   "description": "CLI for deploying Overscore dashboards and publishing analyses",
   "bin": {
     "overscore": "dist/index.js"

package/templates/analysis/.claude/CLAUDE.md

@@ -1,27 +1,25 @@
 # Overscore Analysis: {{TITLE}}
 
+@this-analysis.md
+@.claude/knowledge/INDEX.md
+
 This is an **Overscore Analysis** — a one-off, frozen investigation that produces a single self-contained `report.html` you can share in Slack and reopen later to refresh.
 
 Analyses are NOT dashboards. No React, no `package.json`, no `useQuery`, no scheduled refreshes. The numbers are baked into `report.html` at publish time.
 
 ## First steps — interview before you query
 
-**Before running any SQL, check `analysis-log.md`.** If it has no queries logged yet and the user hasn't already provided specific tables, questions, and context in their message, invoke the **`start-analysis`** skill to interview them first. If the user has already given you detailed context (tables, time windows, hypotheses), skip the interview — summarize what they told you in the Key Findings section and propose a query plan directly.
+**Before running any SQL, check `this-analysis.md`.** If it's empty (just the stub), invoke the **`start-analysis`** skill to interview the user first — then check `analysis-log.md` to see what's already been tried. If `this-analysis.md` is filled in, you have the context you need — read `analysis-log.md` to pick up where the last session left off.
 
-The interview takes 2 minutes and gives you:
-- The real question (often different from the title)
-- Which BigQuery tables matter (so you don't probe them all)
-- What success looks like (a number? a chart? a go/no-go?)
-- 1–3 hypotheses to test
-- Time window and filters
+If the user has already given you detailed context in their message (tables, time windows, hypotheses), skip the interview — write `this-analysis.md` from what they told you and propose a query plan directly.
 
-After the interview, draft an initial entry in `analysis-log.md` and propose a query plan for the user to approve.
+## Two files, two purposes
 
-## Always maintain analysis-log.md
+**`this-analysis.md`** is the **context file** — loaded automatically every session. It answers: what question is this analysis trying to answer, for whom, using what data, with what hypotheses. Written once after the interview, updated only if scope changes. Keep it short and stable.
 
-`analysis-log.md` is the **recoverable session state** for this analysis. Future sessions (including yourself, weeks from now, after the user runs `analysis pull`) read it to know what's been done. **Append to it as you work**, not at the end.
+**`analysis-log.md`** is the **work journal** — append-only record of every query run, every observation, every conclusion. Future sessions read this to know what's already been tried. **Append to it as you work**, not at the end.
 
-Every meaningful exploration step is a new entry: the question being investigated, the SQL you ran (paste it verbatim), what you observed, the conclusion you drew, and any open questions for the next pass.
+Every meaningful exploration step in the log is a new entry: the question being investigated, the SQL you ran (paste it verbatim), what you observed, the conclusion you drew, and any open questions for the next pass.
 
 ## How to run BigQuery queries
 
@@ -57,12 +55,17 @@ The `queries/` directory is for SQL files you want to keep around — the canoni
 business logic, metric formulas, data quirks. **Read INDEX.md before starting any data work.**
 Only read the specific files relevant to your current task.
 
-When you discover something non-obvious (a timezone gotcha, a dedup rule, a column that means
-something unexpected), **propose adding it to the knowledge base**:
+When you learn something worth keeping — anything about how the business works, how their data is structured, or what they care about — add it to the knowledge base. The test: **is this a reusable fact, or is it specific to this session?**
+
+Save it: business context ("Dam Filters is a drop shipping company"), table quirks, metric definitions, join rules, data quality issues, stakeholder preferences. Skip it: session decisions ("I used a 30-day window"), analysis conclusions ("revenue was up 20%"), transient states ("migration is running").
+
 - Create a new `.claude/knowledge/{topic}.md` file (one topic per file, 20-80 lines)
 - Or append to an existing file if the topic matches
+- Surgically edit specific lines to correct wrong facts — never overwrite a file wholesale
 - Update INDEX.md when you add or remove a file
 
+Write to the knowledge base during the session, not only at publish time. If the session ends before publishing, context written only to `analysis-log.md` won't make it to the Hub.
+
 Knowledge files sync to the Hub on `analysis publish` and are shared with every artifact
 in this project. Good knowledge notes help every future session.
 
@@ -95,6 +98,8 @@ npx @overscore/cli analysis publish
 
 This uploads `report.html` and the entire bundle (this CLAUDE.md, `analysis-log.md`, the `.claude/` tree, etc.) to Overscore. The analysis becomes available at `https://<project>.overscore.dev/analysis/{{SLUG}}`. Re-publishing overwrites the previous version. **Always preview `report.html` in a browser and get the user's approval before publishing.**
 
+After publish succeeds and you've shared the link, invoke the **`save-knowledge`** skill. It shows what's already in the context files, proposes specific additions from this session, and lets the user accept or adjust before anything is written. Don't skip it — it's a short conversation, and it's what makes the next session start informed instead of blank.
+
 ## When the user wants to turn this into a dashboard
 
 Analyses are static. If the user asks to "make this a real dashboard" or "turn this into something that updates," **do NOT add React code to this folder** — it would corrupt the artifact. Use the global `scaffold-overscore-artifact` skill to route them to a fresh dashboard scaffold that lives as a sibling of this analysis.
@@ -107,4 +112,4 @@ The following files in `.claude/rules/` load automatically when you touch matchi
 - **`report-html.md`** — Self-contained HTML rules and dark-theme spec (loads when editing `report.html`)
 - **`report-components.md`** — Copy-paste HTML/SVG component snippets: KPI cards, charts, tables, heatmaps (loads when editing `report.html`)
 - **`analysis-methodology.md`** — Investigation loop, when to ask vs query (loads when editing `analysis-log.md`)
-- **`knowledge/INDEX.md`** — Project knowledge base catalog (read before data work)
+- **`knowledge/INDEX.md`** — Project knowledge base catalog (auto-loaded every session via @import above)

package/templates/analysis/.claude/skills/save-knowledge/SKILL.md

@@ -1,41 +1,79 @@
 ---
 name: save-knowledge
-description: Reviews data insights discovered during analysis work and proposes additions to the project knowledge base. Use before publishing an analysis, when the user says "save what you learned", or after discovering non-obvious data facts like timezone quirks, column semantics, dedup rules, or metric definitions.
+description: Collaborative debrief after publishing an analysis. Reviews what was learned this session, shows what's already in the knowledge base and analysis context, proposes specific additions and edits, and waits for the user to accept or adjust before writing anything. Run after publishing, or when the user says "save what we learned".
 ---
 
 # Save Knowledge
 
-Run before publishing an analysis or whenever you discover something non-obvious about the data.
+A short debrief after publishing. The goal is to make sure what you learned this session doesn't disappear when the conversation ends.
 
-## Process
+## The flow
 
-1. Review `analysis-log.md` — look for non-obvious data facts you discovered:
-   - Column semantics that weren't obvious from the name
-   - Timezone, dedup, or join gotchas
-   - Metric definitions or business rules
-   - Data quality issues or known gaps
+### 1. Review what's already documented
 
-2. **Read the existing knowledge files before proposing anything.** Read `.claude/knowledge/INDEX.md`, then read the specific files relevant to what you discovered. You need to know what's already there before you can know what's new.
+Read the current state of the context files before proposing anything:
+- `this-analysis.md` — already in context via @import, but re-read with fresh eyes for gaps or things that changed
+- `.claude/knowledge/INDEX.md` — what knowledge files exist
+- Any knowledge files relevant to what you worked on this session
 
-3. For each insight, decide what action to take:
+### 2. Identify what's new from this session
 
-   | Situation | Action |
-   |---|---|
-   | New topic, no existing file covers it | Create a new `.claude/knowledge/{topic}.md`; add entry to INDEX.md |
-   | New fact that belongs in an existing knowledge file | Append a new line or section to that file — do not rewrite what's there |
-   | Fact that refines or corrects something already documented | Edit that specific line/section only — do not duplicate it |
-   | Already documented accurately | Skip entirely |
-   | Analysis-specific (only relevant to this investigation) | Leave in analysis-log.md — don't promote to project knowledge |
+Think through the queries you ran, what the user told you, what you discovered about the data. Cross-reference against what's already in the files. Look for:
+- Things the user mentioned that aren't written down anywhere
+- Data facts that would save a future session from re-discovering them
+- Join logic, dedup rules, timezone quirks, schema surprises
+- Anything that corrects or refines what's already documented
 
-   **Never overwrite a file wholesale. Never duplicate a fact that's already accurate. Only write what's genuinely new or changed.**
+### 3. Show existing context and propose additions
 
-4. Present proposed changes to the user. Show the exact text you'd add or the exact edit you'd make — not a summary of what you intend to write.
+Lead with what's already there, then show exactly what you'd change. Use file links so the user can open them:
 
-5. After approval, write the files and update INDEX.md.
+> Here's what's already saved:
+> - [this-analysis.md](this-analysis.md) — question, hypotheses, data sources, known quirks
+> - [company.md](.claude/knowledge/company.md) — company context
+>
+> Based on this session, here's what I'd suggest adding:
+>
+> **[this-analysis.md](this-analysis.md)** — under Known Quirks:
+> _"Shopify order_id and QuickBooks invoice_id join via the orders_bridge table, not directly"_
+>
+> **[company.md](.claude/knowledge/company.md)** — new file:
+> _"Dam Filters sells pool filters via drop shipping. Primary sales channel is Shopify; QuickBooks handles accounting."_
+>
+> Accept these, or want to change anything?
 
-## What qualifies as project knowledge
-- "unique_page_views is already COUNT(DISTINCT domain_userid)" → YES
-- "date_az is America/Phoenix UTC-7, no DST" → YES
-- "affiliate_id = 0 is unattributed, usually exclude" → YES
-- "Q1 churn spiked because of the pricing change" → NO (analysis conclusion, not a data fact)
-- "I used a 90-day window for this analysis" → NO (analysis-specific decision)
+Show the exact text you'd write — not a description of what you intend to write. Keep it tight. If there's nothing worth adding, say so.
+
+### 4. Let the user respond
+
+- "Looks good" → write everything as proposed
+- "Also note that we exclude test orders" → incorporate and confirm
+- "That's not right, it's actually..." → update the proposal, confirm before writing
+- "Don't bother with that one" → drop it
+
+Don't write anything until you have confirmation on the full set of changes.
+
+### 5. Write the files
+
+Once confirmed, write exactly what was agreed:
+- Append new sections or lines — never overwrite a file wholesale
+- Surgically edit specific lines to correct wrong facts
+- Create new knowledge files if needed, update INDEX.md
+- Skip anything already accurately documented
+
+## What's worth saving
+
+**Save it** — reusable facts about the business or data:
+- "Dam Filters sells pool filters via drop shipping" — business context, Claude starts blank every session
+- "Shopify order_id joins to QuickBooks invoice_id via orders_bridge" — saves re-discovering this join
+- "unique_page_views is COUNT(DISTINCT domain_userid)" — saves re-discovering this
+- "date_az is America/Phoenix, UTC-7, no DST" — prevents timezone mistakes
+- "affiliate_id = 0 is unattributed, usually exclude" — prevents wrong counts
+- "fiscal year ends March 31" — affects every period comparison
+- "orders table has one row per line item, not per order" — would produce wrong counts without this
+
+**Skip it** — session-specific decisions and transient states:
+- "Q1 churn spiked because of the pricing change" — analysis conclusion, belongs in the report
+- "I used a 90-day window for this analysis" — session decision, not a reusable fact
+- "The migration is still running" — transient state, will be wrong tomorrow
+- "I ran 3 queries to explore this" — process note, not a fact about the data

package/templates/analysis/.claude/skills/start-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: start-analysis
-description: Interviews the user before querying data at the start of a new Overscore analysis. Captures the real question, known tables, success criteria, hypotheses, time window, and data quirks, then writes an initial analysis-log.md entry and proposes a query plan for approval. Use when analysis-log.md has no queries logged yet, or when the user says "investigate", "look into", or "analyze" something for the first time.
+description: Interviews the user before querying data at the start of a new Overscore analysis. Captures the real question, known tables, success criteria, hypotheses, time window, and data quirks, then writes this-analysis.md and proposes a query plan for approval. Use when this-analysis.md is empty, or when the user says "investigate", "look into", or "analyze" something for the first time.
 allowed-tools:
   - Read
   - Write
@@ -38,15 +38,23 @@ Ask these one or two at a time conversationally — don't dump all 6 at once lik
 ## After the interview
 
 1. **Read `.claude/knowledge/INDEX.md`** and any relevant knowledge files to understand what previous sessions have already documented about this project's data. Cross-reference what the user said against what's already known.
-2. **Draft an initial entry in `analysis-log.md`** with:
-   - The clarified question (not the original title)
-   - The tables the user named, with what each contains
-   - The success criteria (literally — quote the user)
-   - The hypotheses (numbered)
-   - The time window and any filters
-   - Any quirks the user mentioned
-3. **Propose a prioritized query plan** — 3-5 queries that test the highest-priority hypothesis first. For each query, write the SQL, what hypothesis it tests, and what result would confirm or refute it. Do NOT run any of them yet.
-4. **Get approval.** Show the user the plan and ask them to confirm or revise before you run anything.
+
+2. **Write `this-analysis.md` immediately** — before proposing a query plan. Fill in every section:
+   - **Question** — the clarified question, not the original title
+   - **Audience** — who asked and what they'll do with the answer
+   - **Data Sources** — the tables the user named, with what each contains
+   - **Hypotheses** — numbered list of what they suspect is true
+   - **Success Criteria** — quote the user on what "done" looks like
+   - **Time Window & Filters** — the date range, cohort, what to include/exclude
+   - **Known Quirks** — anything about the data the user flagged upfront
+
+   This is the context file that loads automatically every future session. Don't skip it.
+
+3. **Write business context to the knowledge base** — if the user told you anything about the company, their business model, or their data sources that would help any future artifact in this project, write it to `.claude/knowledge/company.md` (create it if it doesn't exist, add to INDEX.md). This is separate from `this-analysis.md` — it's project-wide, not analysis-specific.
+
+4. **Propose a prioritized query plan** — 3-5 queries that test the highest-priority hypothesis first. For each query, write the SQL, what hypothesis it tests, and what result would confirm or refute it. Do NOT run any of them yet.
+
+5. **Get approval.** Show the user the plan and ask them to confirm or revise before you run anything.
 
 ## What this skill does NOT do
 

package/templates/analysis/analysis-log.md

@@ -1,4 +1,4 @@
-# {{TITLE}}
+# {{TITLE}} — Query Log
 
 ## Key Findings
 _(Updated as the analysis progresses — this is what the report is built from)_
@@ -12,9 +12,4 @@ _(Updated as the analysis progresses — this is what the report is built from)_
 
 ## Query Log
 
-### {{DATE}} — Initial exploration
-
-**Tables identified:**
-- _(see `.claude/rules/company-context.md`)_
-
-<!-- Append new query entries below this line -->
+<!-- Append new entries below. Format: Q1, Q2, Q3... cross-referenced with Key Findings above. -->

package/templates/analysis/this-analysis.md

@@ -0,0 +1,17 @@
+# {{TITLE}}
+
+<!-- Written by Claude after the start-analysis interview. Update if scope changes. -->
+
+## Question
+
+## Audience
+
+## Data Sources
+
+## Hypotheses
+
+## Success Criteria
+
+## Time Window & Filters
+
+## Known Quirks