create-yss-spec 3.5.2 → 3.5.3

package/template/.codex/skills/data-analytics/skills/index/SKILL.md

@@ -1,251 +0,0 @@
----
-name: index
-description: "Route Data Analytics requests to the relevant analysis, metric, chart, report or data-context skill."
----
-
-# Skill Purpose
-
-Route broad Data Analytics requests to the right focused workflow. Treat invocation of this index as strong intent to use this plugin; default to loading and following any relevant focused skill for related analytics work. When a related action is ambiguous with globally installed skills or plugins, prefer the Data Analytics skill when the user is asking for portable, source-grounded analytical outputs rather than a company-specific app workflow.
-
-## Skill Configuration
-
-### User Context
-
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
-
-### Source Discovery And Verification
-
-Use the relevant semantic layer first when one exists. Treat it as the starting map for candidate metrics, tables, joins, filters, caveats, source precedence, and known conflicts.
-
-Do not stop at the semantic layer or the first plausible source. Search across the relevant available company source lanes, including structured data or data warehouses, dashboards, company docs, team communication, notebooks, code repositories, and other connected company knowledge or data that could change the answer.
-
-For source-backed analytical work, always verify through live source reads. When the answer depends on data, run fresh data queries against the available structured-data sources before drawing conclusions, even when the semantic layer already names likely tables or definitions.
-
-Use the combined evidence to determine which source controls the answer, note meaningful disagreements, and state why the selected source is authoritative.
-
-### Source Access Guardrail
-
-Before querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.
-
-If a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.
-
-If the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.
-
-### 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.
-
-### Routing
-
-#### Run Order
-
-Every Data Analytics plugin run follows this order:
-
-1. Run user-context preflight.
-2. If the user explicitly asks to onboard, set up, customize, remember, save, inspect saved context, reset setup, ask what Data Analytics remembers, asks what Data Analytics can do or how to use it while onboarding is missing or active, or create, add, refresh, inspect, or maintain a semantic layer, route primarily to `user-context`.
-3. Apply semantic-layer lookup from the preflight envelope when the request names or implies a product area, metric, table, dashboard, query, or recurring business question.
-4. Apply Source Discovery And Verification before source queries, document search, notebook work, report building, dashboard wiring, or conclusions.
-5. Apply the Source Access Guardrail before source queries, document search, notebook work, report building, dashboard wiring, or conclusions.
-6. Choose the response mode: `inline` for bounded lookups and `report` for explanations, decompositions, recommendations, or larger analytical answers.
-7. Select the minimal primary/supporting skills, then do one companion-skill pass across installed skills for clearer non-analytics surfaces, semantic layers, or methods.
-8. Read and follow the selected skill bodies before source queries, report building, supporting-skill execution, or final drafting.
-9. Before final response, apply the focused workflow's completion gates plus any preflight `final_obligations`.
-
-#### Response Mode
-
-Use `inline` for bounded factual or computational answers that can be delivered in chat without a durable artifact: metric lookups, schema or table questions, one-cut rankings, and simple comparisons.
-
-Treat short quantitative prompts as Data Analytics work when answering them requires explaining how numbers compare, break down, concentrate, or move across multiple values, groups, or time points. Keep these routes lightweight by default: use `inline` for bounded answers and escalate to `report` only when the user asks for explanation, diagnosis, recommendation, or a durable artifact.
-
-Use `report` for explanation, diagnosis, decomposition, synthesis, recommendation, or larger analytical answers whose value materially improves from a durable artifact. When the user asks to interpret analytical source material or reviewed results, choose report mode when the answer needs evidence-backed narrative, caveats, source metadata, or a reader-facing artifact. The focused skill name does not determine delivery mode. Preserve the user-selected `inline`, `report`, `local` file or `native` cloud target. A bounded KPI/diagnostic answer can remain inline; use $build-report only for a selected report deliverable. Cloud upload/sharing requires the corresponding user request and available capability.
-
-After choosing `inline` or `report`, use `$visualize-data` when a visual would make the result easier to understand, especially for category comparisons, part-to-whole breakdowns, rankings, movement over time, or more than a handful of comparable values, rows, categories, or time points. Prefer a visual pass over a scan-heavy table, and let `$visualize-data` choose the form, decide whether to render a chart, and align any table or prose to the visual takeaway.
-
-#### Skill Selection
-
-- Pick the smallest useful set of primary/supporting skills.
-- For report-mode runs, state the selected route once in a progress update, such as `Route: product-business-analysis + product semantic layer + build-report`.
-- Use `user-context` for explicit onboarding/setup/context requests and for durable Data Analytics preferences, source pointers, semantic-layer registry, semantic-layer setup or maintenance, or saved workflow notes.
-- Treat a plugin mention as a starting point, not a boundary. Add an installed external skill whenever it is the clearer owner of a complementary subtask, runtime surface, delivery surface, artifact type, or domain-specific method.
-- Do not reject an external skill merely because a bundled Data Analytics skill partially overlaps with it.
-- Do not maintain worked route recipes here. Once selected, the chosen skills own detailed step order, supporting triggers, and output contracts.
-- When a request maps to a primary workflow, load that workflow skill directly. For example, a KPI design prompt must read `$design-kpis`, a dashboard prompt must read `$build-dashboard`, a TAM/SAM/SOM prompt must read `$market-sizing`, a metric movement prompt must read `$metric-diagnostics`, and a recommendation-oriented product or business decision prompt must read `$product-business-analysis`.
-
-If several focused skills apply, sequence them in the order that creates the most useful analyst workflow. For example, metric diagnostics may precede KPI reporting, semantic-layer setup may precede dashboard or report work, and product-business analysis may feed a recommendation-ready report. Keep this index as a router; do not perform focused workflow logic here.
-
-Before finalizing future Data Analytics instruction edits, run `python3 .codex/skills/data-analytics/skills/user-context/scripts/validate_user_context_preflight.py .codex/skills/data-analytics` from the repository root. Treat a missing mandatory pre-answer gate in any `SKILL.md`, including helper skills, as an audit finding to fix before release.
-
-Prefer examples that route to focused skills without extra setup, such as:
-
-```text
-@Data Analytics diagnose why subscription ARR moved last week.
-@Data Analytics build a KPI framework for the customer onboarding funnel.
-@Data Analytics analyze paid workspace retention and recommend what to investigate next.
-```
-
-For follow-up messages such as "yes", "walk me through it", "what happened?", or "show the steps" immediately after a completed guided workflow offers a walkthrough, route to `user-context` and use `../user-context/references/onboarding.md#workflow-walkthrough-on-request`. Explain the observable steps, tool/app calls, retrievals, source gaps, and artifact assembly at a beginner-friendly level without revealing hidden reasoning.
-
-### Broad Orientation And Help Requests
-
-For broad orientation and help requests:
-
-- Handle open-ended Data Analytics asks from this index before choosing a focused workflow.
-- Route requests such as `what can you do?`, `help`, `orient me`, `what should I try first?`, `how do I use Data Analytics?`, setup-adjacent capability questions, and similar plugin-level requests here when the user needs orientation more than a specific artifact.
-- Before using this index-level help answer, check the preflight onboarding status. If onboarding is missing or active and the user asks `what can you do?`, `orient me`, `what should I try first?`, `how do I use Data Analytics?`, or another setup-adjacent capability question, route to `user-context` and render the current onboarding step from `../user-context/references/onboarding.md` instead of this default skill-map answer.
-- Use this index-level help answer when onboarding is complete or quiet, or when the user explicitly asks for a compact capability summary without resuming setup.
-- Answer from the skill map in this file using the default shape below.
-- Include concrete low-friction next prompts that start with `@Data Analytics`, name the analytics job, and use a realistic anchor.
-- Include a short setup context section from the `data_analytics_preflight.context.connector_setup_summary` envelope when any source is not active, needs a user choice, was skipped, or is otherwise unresolved.
-- Keep setup context analyst-facing: name the practical source, use model judgment to explain the likely user-experience impact from the source label, configured preferred routes, setup action, and suggested next prompts, then give the smallest next action or fallback.
-- Show at most three highest-impact gaps by default, and never more than five setup-context bullets total. Prioritize gaps in the order most relevant to the examples you are suggesting rather than following a hard-coded impact catalog.
-- If all sources are active, keep setup context to one sentence such as `Your core Data Analytics sources look ready; I'll still try each source only when a workflow needs it.`
-- When the current context or available sources identify a real metric, product area, dashboard, table, SQL query, semantic layer, experiment, funnel, cohort, or decision question, use the relevant focused skill's inline first-run and next-step guidance to make the suggested prompt contextual.
-- For setup context wording, be direct and practical, for example: `You won't be able to properly validate a metric from live tables until a warehouse or SQL source is available, but you can paste SQL, schema details, or exported query results for now.`
-- Use static examples only when no suitable context is available.
-- Do not expose raw status names, onboarding state fields, connector ids, or implementation terms.
-- Do not perform connector reads merely to answer a capability question; use the preflight setup summary and any current session app or tool availability already visible in context.
-
-Use this default answer shape for broad orientation and help requests:
-
-```md
-Data Analytics can help with:
-- Metric diagnostics and source-backed explanations for movement
-- KPI design, metric definitions, and measurement frameworks
-- Product and business analysis for funnels, retention, adoption, pricing, and strategic decisions
-- KPI reports, dashboards, notebooks, and reusable semantic layers
-- Market sizing, opportunity sizing, and decision-ready recommendations
-
-Setup context:
-- {Only include when useful: source readiness or gap plus practical impact}
-
-Good first prompts:
-- `@Data Analytics diagnose why subscription ARR moved last week.`
-- `@Data Analytics build a KPI framework for the customer onboarding funnel.`
-- `@Data Analytics analyze paid workspace retention and recommend what to investigate next.`
-```
-
-# Plugin Purpose
-
-Data Analytics turns connected or provided business data, source-of-truth context, dashboards, docs, chats, notebooks, spreadsheets, SQL, and semantic layers into source-backed analytical work products. It can define KPIs, diagnose metric movement, size markets, analyze product or business questions, validate data quality, gather context, build reproducible notebooks, design visualizations, create dashboards, produce polished reports, and convert those outputs into shareable Docs, Slides, spreadsheets, or other durable handoff surfaces.
-
-## Semantic Layers
-
-Semantic layers are source-backed local skills for product, business, metric, source, or reporting areas. They encode canonical metrics, tables, grains, joins, filters, query patterns, caveats, source precedence, and validation gaps.
-
-Before answering questions about a named product area, metric, table, dashboard, SQL query, source choice, join, caveat, or recurring business question, inspect the `semantic_layers` registry returned by user-context preflight and installed skills whose name or description matches `<area>-semantic-layer`, `<area>-data-semantics`, or equivalent semantic-layer wording. If a relevant semantic-layer skill exists, read it before selecting tables, writing SQL, reconciling dashboards, or giving metric definitions. Treat it as the domain-specific semantic map, then consult the connected or provided apps and verify high-stakes claims against the layer's cited sources.
-
-When no relevant semantic layer exists and the user is asking a repeatable domain question, offer semantic-layer setup through `user-context`. Users can create multiple semantic layers for multiple product or business areas. Do not merge unrelated product areas into one broad layer unless the user explicitly asks for a cross-product semantic layer.
-
-## Evidence And Handoff
-
-Data Analytics plugin files use lane placeholders such as `~~structured_data` for whatever tool, connector, MCP server, plugin skill, pasted result, uploaded file, or schema description is available in that category. See [DEPENDENCIES.MD](../../DEPENDENCIES.MD) for provider options. When a required connector, plugin, MCP server, or source-of-truth lane is unavailable, follow the Source Access Guardrail. When an optional lane is unavailable, continue from pasted query results, uploaded files, SQL snippets, screenshots, schema descriptions, or other reviewed evidence and label the gap when it materially affects the answer.
-
-Source rules:
-
-- Gather source-of-truth context before writing SQL, notebook code, dashboards, reports, or conclusions.
-- Prefer reproducible notebooks for fresh SQL, Python, statistics, modeling, source reconciliation, or non-trivial metric computation when a notebook materially improves auditability.
-- Preserve relevant SQL, scripts, query permalinks, outputs, source links, and caveats in the final artifact or supporting notes.
-
-Delivery surface boundary:
-
-- Startup must work when the user does not want MCP widget or MCP artifact rendering. In that case, continue through the selected chat, notebook, SQL, HTML, BI, Streamlit, spreadsheet, slide, or other non-MCP surface and keep source notes in that surface's normal supporting artifacts.
-- Use MCP inline widgets or the unified MCP artifact app only when that delivery surface has been selected, is safe, and has not been waived by the user. Before shaping widget/app-specific artifacts, read `../../src/analytics-app-core.md`; keep MCP mechanics out of this startup router.
-- Do not expose hidden reasoning, credentials, secrets, direct personal contact/payment identifiers, or unvalidated calculations in any user-facing surface. Reviewed customer, account, or company names may be included when they are needed for the analysis.
-- Once the analysis commits to a source table in an inline or dashboard route, expose a small deterministic preview when safe through the selected surface's normal preview mechanism.
-- If a preview is unsafe, unavailable, or blocked by access limits, record that briefly and continue from schema, documentation, or other reviewed evidence.
-
-## Completion Gates
-
-Report completion:
-
-- The report run must choose exactly one report delivery mode through `$build-report`.
-- Choose a non-MCP delivery mode when the user asks for HTML, file/blob sharing, Docs/Slides conversion, offline portability, no MCP app/widget rendering, or when MCP artifact rendering is unavailable, unsafe, or over bounds.
-- Do not end with only an inline/chat summary or a localhost URL. Treat chat summaries as progress updates.
-- If a required deliverable is skipped, include the explicit omission reason in the final handoff.
-- HTML report charts must be Seaborn-generated PNG images.
-- If the report includes charts, evidence tables, or custom visualizations, satisfy $visualize-data's chart contract and QA before embedding them.
-
-Final review:
-
-- Verify generated artifacts by opening, reading, rendering, or otherwise inspecting them.
-- Check source-backed claims against the controlling sources used for the analysis.
-- Call out unresolved gaps or caveats when they materially affect the conclusion.
-- Verify that every selected primary workflow skill was read and followed. If a primary workflow was skipped, record why in the final handoff. Do not treat a semantic-layer lookup, notebook, validation pass, visualization, or report artifact as satisfying the primary workflow contract.
-- If the run was classified as `report`, do not finalize until the downstream $build-report contract has either passed or been explicitly blocked.
-- If a selected rendering surface is unsafe, unavailable, too large, or fails after a targeted retry, continue the analysis through another appropriate surface and briefly note the reason in the progress update or final handoff.
-
-## Skills
-
-### design-kpis
-
-Use $design-kpis for goals, primary KPIs, driver metrics, guardrails, scorecards, measurement plans, and launch or experiment success criteria.
-
-### kpi-reporting
-
-Use $kpi-reporting for KPI updates, scorecards, business reviews, executive metric summaries, target or pacing readouts, and leadership-ready performance narratives. Add $metric-diagnostics when the update must explain why a KPI moved.
-
-### market-sizing
-
-Use $market-sizing for TAM/SAM/SOM, opportunity, spend or revenue pool, customer count, unit volume, commercial upside, and sensitivity models.
-
-### metric-diagnostics
-
-Use $metric-diagnostics to identify what drove a metric over a defined time period, baseline, or segment comparison, rule out measurement artifacts, label findings by certainty, and route the final report through $build-report.
-
-### product-business-analysis
-
-Use $product-business-analysis to analyze product or business data and context for recommendation-oriented decisions. Add $metric-diagnostics when the recommendation depends on validated metric movement.
-
-### analyze-data-quality
-
-Use $analyze-data-quality for freshness, grain, row counts, nulls, duplicates, schema drift, broken joins, outliers, backfills, and source or dashboard disagreement.
-
-### build-dashboard
-
-Use $build-dashboard for analytical dashboards, scorecards, monitoring pages, BI views, Streamlit dashboards, MCP artifact dashboards, BI platform dashboards, and dashboard QA.
-
-### build-report
-
-Use $build-report to build exactly one durable report surface selected for the user request, such as an MCP app report or an HTML report with Seaborn-generated PNG charts.
-
-### report-to-google-doc
-
-Use $report-to-google-doc for HTML → local DOCX. Hosted DOCX and native Google Docs are separate optional targets: discover capabilities, preserve user intent, and verify the actual result type before claiming a native document.
-
-### report-to-google-slides
-
-Use $report-to-google-slides to convert an existing local HTML report into a polished native Google Slides deck.
-
-### report-to-pdf
-
-Use $report-to-pdf to convert an existing static Data Analytics report export into a verified PDF artifact.
-
-### gather-business-context
-
-Use $gather-business-context for docs, dashboards, chats, planning notes, launch or experiment material, source-of-truth pages, owners, incidents, roadmap, GTM or customer context, and prior decisions.
-
-### jupyter-notebooks
-
-Use $jupyter-notebooks to create, edit, and verify reproducible notebooks for SQL, Python, statistics, modeling, cohort or funnel analysis, data-quality checks, experiments, market sizing, diagnostics, and report support.
-
-### spreadsheets
-
-Use $spreadsheets to create, edit, inspect, render, verify, export, or Google Sheets-handoff spreadsheet artifacts.
-
-### validate-data
-
-Use $validate-data to QA methodology, source selection, SQL or query logic, calculations, visualization integrity, caveats, and whether conclusions are supported by evidence.
-
-### visualize-data
-
-Use $visualize-data to design, implement, and QA charts for reports, dashboards, decks, notebooks, scorecards, trends, decompositions, funnels, cohorts, distributions, uncertainty, and executive KPI readouts.
-
-### user-context
-
-Use `user-context` as the Data Analytics durable context, setup, onboarding, semantic-layer registry, and saved preference owner. Route explicit onboarding, setup, customization, remember or save requests, saved-context inspection, and reset requests here.

package/template/.codex/skills/data-analytics/skills/index/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Index"
-  short_description: "Route broad Data Analytics workflow and setup requests"
-  default_prompt: "Help me choose the right Data Analytics workflow for this analysis task."
-policy:
-  allow_implicit_invocation: true

package/template/.codex/skills/data-analytics/skills/jupyter-notebooks/SKILL.md

@@ -1,131 +0,0 @@
----
-name: jupyter-notebooks
-description: "Create or revise a reproducible Jupyter notebook when the notebook itself is a deliverable or runnable analysis."
----
-
-# Jupyter Notebooks
-
-Create clean, reproducible Jupyter notebooks that are easy to skim, rerun, and handoff. Treat the notebook as a reader-facing analysis artifact, not a scratchpad dump. Notebook work is not complete until the notebook executes successfully top-to-bottom, or the execution gap is called out with the exact validation steps needed to reproduce it.
-
-## Skill Configuration
-
-### User Context
-
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
-
-## Workflow
-
-1. Lock the notebook mode and scope.
-
-   Decide whether the notebook is an analysis report, experiment log, diagnostic notebook, data-quality check, market-sizing calculation, model exploration,
-   tutorial, or companion artifact for a report. Identify the reader, decision,
-   expected handoff, required inputs, and whether the task calls for a new notebook or targeted edits to an existing one.
-
-2. Inspect or scaffold with notebook-safe tooling.
-
-   Prefer JupyterLab, `nbformat`, `nbclient`, or an existing scaffold utility over hand-editing raw JSON. When editing an existing notebook, preserve its intent and minimize JSON churn. Avoid reordering cells unless it clearly improves the top-to-bottom story. If raw JSON editing is unavoidable,
-   validate the notebook structure before finishing.
-
-3. Structure the notebook for the chosen mode.
-
-   For analytical notebooks, default to:
-
-   1. `## tl;dr`
-   2. `## Context & Methods`
-   3. `## Data`
-   4. `## Results`
-   5. `## Takeaways`
-
-   Write `tl;dr` and takeaways after reviewing executed outputs. Use concrete observed values, visible patterns, rows, or charts, not assumptions. Include a `### Key Assumptions` subsection in `Context & Methods` when assumptions affect correctness.
-
-   For tutorials or walkthroughs, adapt the same discipline to a teaching flow:
-
-   1. `## Goal`
-   2. `## Setup`
-   3. `## Steps`
-   4. `## Checks`
-   5. `## Next Steps`
-
-4. Build a clear data and computation path.
-
-   Separate setup, imports, parameters, data loading, data preparation,
-   calculations, visualizations, and interpretation. If the notebook uses both SQL and Python, keep complex SQL in SQL cells or separate query files rather than large embedded Python strings unless there is a clear reason. Use descriptive variable names and keep each code cell focused on one step.
-
-5. Use data sources deliberately.
-
-   When a notebook needs table data, first use `~~structured_data` to confirm table choice, schema, partition filters, sample rows, and query-submission policy. Use the relevant source connector when available, then fall back to exports or pasted SQL when needed. Use `~~operations_logs` for freshness or lineage checks when they matter. Record query permalinks, request IDs, source paths, dashboard links,
-   extract names, or other source artifacts in the notebook context for any executed result that supports the analysis. Keep heavy queries filtered and bounded instead of turning the notebook into a broad live-source scan.
-
-6. Make cells readable and bounded.
-
-   Add concise markdown headers before most code cells. Keep headers brief and action-oriented, such as `### 1. Load Data`, `### 2. Validate Inputs`, or `### 3. Plot Results`. Favor several short cells over one large mixed-purpose cell. Keep prose short: explain purpose, assumptions, and expected result, not every line of code. Split multiple tables or charts across separate cells instead of dumping all outputs from one cell.
-
-7. Validate results before writing conclusions.
-
-   Check that key numbers, charts, and takeaways match executed outputs. Bound raw debug output, oversized tables, and noisy logs. If a result is surprising, add a local reasonableness check, small sample inspection, or reconciliation against a trusted source before promoting it to the summary.
-
-8. Execute and record validation status.
-
-   Run the notebook top-to-bottom when the environment allows:
-
-   ```bash
-   python -m jupyter nbconvert --execute --to notebook --inplace path/to/notebook.ipynb
-   ```
-
-   Optional local setup when needed:
-
-   ```bash
-   uv pip install jupyterlab nbformat nbclient ipykernel
-   ```
-
-   If execution is not possible, say so explicitly and provide the exact command,
-   missing dependency, credential, data access, kernel, or environment step needed to validate locally.
-
-## Standards
-
-### Notebook Structure
-
-- Make the default top-to-bottom read clear before the reader starts executing cells out of order.
-- Put executive summary material at the top, but write it last after inspecting executed results.
-- Keep notebook sections aligned with the notebook mode: analysis, experiment,
-  diagnostic, tutorial, or handoff artifact.
-- Keep section titles, chart titles, labels, and file names descriptive enough for handoff.
-- Preserve the existing notebook's intent when refactoring; improve structure without rewriting everything by default.
-
-### Reproducibility
-
-- Keep parameters, date ranges, filters, cohorts, assumptions, and source references visible near the top of the notebook.
-- Record enough source context for another reader to trace the analysis: query permalinks, request IDs, table names, source paths, spreadsheet tabs,
-  dashboard links, extract versions, or input file locations.
-- Make computation deterministic where possible. Avoid hidden state, manually edited intermediate values, out-of-order dependencies, and unexplained cached outputs.
-- Prefer explicit environment setup cells or notes when the notebook depends on nonstandard packages, kernels, credentials, or local files.
-- Include validation status in the final response: executed successfully,
-  partially executed, or not executed, with the reason.
-
-### Code And Data Hygiene
-
-- Separate data preparation from presentation.
-- Keep complex SQL readable and documented with a one-line goal comment.
-- Keep plotting and lightweight shaping in Python after the data preparation step is complete.
-- Use descriptive variable names and avoid abbreviated temporary names in reader-facing notebooks.
-- Keep outputs bounded. Prefer small preview tables, sampled rows, explicit limits, and focused charts over raw dumps.
-- Avoid broad live-source scans. Filter queries by needed partitions, cohorts,
-  or time windows.
-
-### Analysis Quality
-
-- Make assumptions explicit when they affect interpretation.
-- Tie takeaways to executed outputs with concrete numbers, rows, charts, or visible patterns.
-- Do not promote unexecuted or unverified calculations into the `tl;dr`.
-- Label caveats, incomplete checks, missing source access, and known validation gaps.
-- Add reasonableness checks for surprising results, high-impact claims, or stakeholder-facing conclusions.
-
-### Validation Checklist
-
-- Required section order is present for the notebook mode.
-- The notebook executes without runtime errors, or execution failure is called out explicitly.
-- Outputs are present where expected and are not dominated by raw debug dumps.
-- The `tl;dr`, results, and takeaways match executed cells.
-- Source references and query or artifact links are preserved.
-- Tables and charts are labeled, bounded, and interpretable.
-- The final response includes the notebook path and validation status.

package/template/.codex/skills/data-analytics/skills/jupyter-notebooks/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Jupyter Notebooks"
-  short_description: "Create and validate reproducible analysis notebooks"
-  default_prompt: "Create a reproducible analysis notebook with inspectable code, outputs, assumptions, and validation checks."
-policy:
-  allow_implicit_invocation: false

package/template/.codex/skills/data-analytics/skills/kpi-reporting/SKILL.md

@@ -1,141 +0,0 @@
----
-name: kpi-reporting
-description: "Report known KPIs against targets or prior periods in scorecards, performance updates and WBR/MBR/QBR summaries."
----
-
-# KPI Reporting
-
-Use this skill to turn business or product metrics into decision-ready operating readouts for leaders and teams. The job is to define the KPI contract, report status against the right comparison and target, include validated driver context, and state the operating implication clearly.
-
-Clarify with the user when a missing input would materially change the analytical frame or recommendation. Otherwise make a reasonable assumption, state it, and proceed.
-
-This skill owns the KPI readout: what should be reported, how metrics should be interpreted, whether driver context is validated, and what operating takeaway follows. It does not own metric-system design, new driver investigation, or final artifact polish.
-
-Use $metric-diagnostics when the readout needs fresh driver investigation, then return here to package the validated finding.
-
-## Skill Configuration
-
-### User Context
-
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
-
-### Source Discovery And Verification
-
-Use the relevant semantic layer first when one exists. Treat it as the starting map for candidate metrics, tables, joins, filters, caveats, source precedence, and known conflicts.
-
-Do not stop at the semantic layer or the first plausible source. Search across the relevant available company source lanes, including structured data or data warehouses, dashboards, company docs, team communication, notebooks, code repositories, and other connected company knowledge or data that could change the answer.
-
-For source-backed analytical work, always verify through live source reads. When the answer depends on data, run fresh data queries against the available structured-data sources before drawing conclusions, even when the semantic layer already names likely tables or definitions.
-
-Use the combined evidence to determine which source controls the answer, note meaningful disagreements, and state why the selected source is authoritative.
-
-### Source Access Guardrail
-
-Before querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.
-
-If a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.
-
-If the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.
-
-## Workflow
-
-### 1. Clarify The Readout Purpose
-
-Understand who the readout is for, what conversation it supports, and what is being reported before drafting. Anchor the update in the period being evaluated, the comparison or target that makes performance interpretable, and the freshness cutoff.
-
-Ask the user for missing context when it would help make the readout more accurate or useful.
-
-### 2. Define The Metric Framework
-
-Decide which metrics belong in the readout and what role each one plays before pulling numbers. If the framework already exists, confirm it and use it. If it is missing or weak, use $design-kpis before reporting.
-
-Start with the primary KPI, then add the smallest set of supporting metrics needed to explain status. Supporting metrics can explain movement, guard against harmful tradeoffs, or show whether performance is pacing as expected.
-
-Lead with the metric that matters most to the audience. Do not add every available cut or comparison; include the metrics and slices decision-makers actually use, plus any that materially explain this update.
-
-### 3. Lock Metric Definitions And Sources
-
-Confirm the KPI definition, source, time window, reporting cutoff, comparison period, and any target or pacing expectation before interpreting performance. If a target or pacing basis is missing, ask before treating one as authoritative. Use $analyze-data-quality when source quality issues could change the reported metrics.
-
-For all KPI updates, make a focused source pass across `~~structured_data`, `~~company_docs`, `~~team_communication`, and `~~dashboards_or_bi` before drafting. Do not infer from a sparse prompt that source-backed actuals are unavailable. Use structured data for actuals, metric definitions, and comparison periods; use the other lanes for additional business context and source-of-truth guidance.
-
-If any core definition is unclear, ask the user to clarify before making precise claims. When a metric definition changed, show comparable restated history when available; otherwise call out the break clearly.
-
-### 4. Pull The Topline Actuals
-
-Do not draft or render a WBR, MBR, scorecard, or KPI update from placeholders. Query or inspect connected structured-data sources for core actuals first. If actuals are blocked or insufficient, stop and say what source or access is needed unless the user explicitly asked for a template or mockup.
-
-Reproduce the topline actual before explaining movement or driver context.
-
-For each headline KPI, include the current value, the absolute and relative change versus the comparison period, and a short interpretation.
-
-Call out anything that makes the current value hard to compare with the prior period before interpreting the movement, such as a tracking change, data backfill, partial outage, or missing day.
-
-### 5. Put The Numbers In Context
-
-Compare actuals against the context that makes performance interpretable. When a target, plan, pacing model, benchmark, historical range, or relevant peer group is defined, identify it and compare performance against it before judging status.
-
-If the goal has a deadline, do not just report whether the metric is above or below target. Show whether it is on pace to hit the target by the end of the period. Use the provided pacing definition when available. If none is defined or found, ask the user; when proceeding with a calculated fallback, state that it was calculated and explain the method.
-
-When useful, include absolute and percent variance to target and a red/yellow/green status. Make clear what comparison or pacing basis the status label uses.
-
-### 6. Explain Validated Drivers
-
-KPI updates need driver context, but driver claims must be validated before they are presented as explanations. A plausible story is not enough.
-
-When the readout needs to explain drivers, use $metric-diagnostics to identify and validate them. If trusted reporting or prior analysis already validates the drivers, use that evidence instead of re-running the diagnostic.
-
-### 7. Add Business Context And Operating Implications
-
-After identifying the likely drivers, use $gather-business-context to look for business context that helps explain what happened and what it means for the readout. Let the driver analysis guide what context to look for, and connect context to the metric only when evidence supports the link.
-
-Translate the evidence, driver analysis, and business context into the operating implication for the business. State whether the movement is concerning, what next step or action is warranted, and whether the main KPI is on track, at risk, or ahead of plan. Recommend action only when the evidence supports it; otherwise name the next validation step.
-
-### 8. Validate The Readout
-
-After the analysis is assembled and before shaping the final readout, use $validate-data to review whether the numbers, methodology, caveats, and evidence support the claimed status, drivers, and implications. Resolve material issues before sharing; carry remaining limitations into the readout.
-
-### 9. Shape The Readout
-
-Use the output shape the user requested. If unspecified, use inline for a bounded readout and infer a durable format only when the task requires it; ask only when the delivery choice materially changes the requested work. Common shapes include an inline written update, a document or report, a slide, or a slide deck.
-
-After the format is selected, load `references/report-templates.md` and use the matching pattern as a starting point. Adapt it to the audience, evidence, and artifact.
-
-Use $build-report for document or report outputs; it will handle report visuals and route chart work through $visualize-data. For inline updates, slides, or deck drafts that do not go through $build-report, use $visualize-data only when chart selection or visual QA materially affects the readout.
-
-For slide or deck requests, use the user's requested output surface. If they want a presentation-style artifact, use $build-report to create a report artifact or HTML. If they need a native slide or deck, finalize the KPI story here, then pass the content to the appropriate presentation surface and keep the layout simple. Ask which path they want when the requested output is unclear.
-
-## Standards
-
-### Metric Standards
-
-- Never present a KPI as precise when its definition, source, time window, or comparison basis is unclear.
-- Make calculation logic, inclusion or exclusion rules, grain, and time treatment explicit when they affect interpretation.
-- Reconcile totals and compare against prior reporting when possible.
-- Do not compare periods, cuts, or targets that are not definitionally compatible. Call out definition changes, backfills, denominator shifts, or calendar effects when they affect the movement.
-
-### Status And Pacing Standards
-
-- Include the headline takeaway, current actual, relevant comparison, target or pacing context, driver summary, and implication unless the user asks for a narrower readout.
-- Put actuals next to the target, plan, benchmark, or baseline when available so the reader can judge performance immediately.
-- If a target is time-bound, show whether current performance is on pace using the provided pacing definition or a clearly stated calculated fallback.
-- Keep recurring metric sections consistent across runs. If a requested section is missing because data, definitions, or validation are unavailable, explain the omission briefly.
-- Use traffic-signal status only when it helps prioritize action. Pair color with text and state the basis for the status.
-- Round numbers consistently, label units, and surface caveats when they change interpretation.
-
-### Driver Standards
-
-- Quantify drivers whenever the evidence supports it; do not use descriptive prose as a substitute for sizing the effect.
-- Report the few drivers, contributors, or known non-drivers that matter for interpreting the KPI movement.
-- Separate validated drivers from business context or hypotheses.
-- Do not elevate business events into causes unless the timing, affected population, and measured change support the link.
-- State whether the movement is broad-based or concentrated when that changes the operating implication.
-- If driver evidence remains unresolved, name the uncertainty or diagnostic follow-up instead of inventing an explanation.
-
-### Presentation Standards
-
-- Write for executives and operators who skim: lead with the answer, then the evidence.
-- Use business-readable numbers and compact formats such as `123k (+8% w/w, +19% m/m)`.
-- Replace generic adjectives like `strong`, `healthy`, or `soft` with the metric evidence that justifies them.
-- Keep caveats close to the claim they affect, and omit caveats that do not change interpretation.
-- Use charts, tables, scorecards, or KPI cards only when they make the takeaway easier to understand and remain readable in the final delivery context.

package/template/.codex/skills/data-analytics/skills/kpi-reporting/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "KPI Reporting"
-  short_description: "Produce leadership-ready KPI updates and scorecards"
-  default_prompt: "Produce a leadership-ready KPI update with current status, comparison, drivers, and implications."
-policy:
-  allow_implicit_invocation: true

package/template/.codex/skills/data-analytics/skills/kpi-reporting/references/report-templates.md

@@ -1,32 +0,0 @@
-# Report Templates
-
-Use this reference after the output format is selected. These are starting patterns, not mandatory layouts.
-
-These templates shape the final artifact only. Complete the KPI Reporting workflow first; analysis, validation, and operating implications come from that workflow.
-
-## Inline Written Update
-
-Use for a short chat, email, or memo-style update. Lead with the answer, then include the headline actuals, comparison or pacing context, main drivers, and the operating implication or next step.
-
-## Document Or Report
-
-Route document and report outputs through $build-report. Use this reference to shape the KPI content passed into that workflow: summary, KPI snapshot, driver analysis, business context, implications, caveats, and reader-relevant source or calculation notes.
-
-## Single Slide
-
-Use for one concise readout. Follow the user's requested surface: $build-report for a report artifact or HTML, or the native presentation surface when the user needs a slide file. Ask which path they want when unclear. A single-slide story should have one main message, a compact view of the headline metrics, and only the driver, risk, or action detail needed to support that message.
-
-## Executive Business Review Deck
-
-Use for larger executive readouts, such as weekly, monthly, or quarterly business reviews. Follow the user's requested surface: $build-report for a report artifact or HTML, or the native presentation surface when the user needs a deck file. Ask which path they want when unclear.
-
-- Give a concise executive summary of overall status, what changed, and what needs attention.
-- Use KPI cards, a scorecard, or another compact summary format that makes headline performance easy to scan; move dense detail into supporting sections.
-- Organize the body around the main drivers of performance. Each section should connect the driver evidence to the operating takeaway, with action, risk, or follow-up when one is warranted.
-- Keep detailed evidence, large tables, and deeper cuts in supporting sections or an appendix.
-- Include prior follow-ups when they are useful for a recurring readout, with ownership and current status.
-- End with the prioritized actions or open questions leaders need to resolve.
-
-## Scorecard Or KPI Card Component
-
-Use a compact scorecard when the reader needs to compare multiple KPIs at once. Include the actual, relevant comparison, target or pacing context when available, status, and a short driver or interpretation. Expand the explanation below the table when the driver story needs more room.