create-yss-spec 3.5.2 → 3.5.3

package/template/.codex/skills/data-analytics/skills/build-report/report-to-pdf/SKILL.md

@@ -1,88 +0,0 @@
----
-name: report-to-pdf
-description: "Narrow conversion skill. Invoke only when the user explicitly asks to convert an existing Data Analytics report, dashboard, or inline chart export into a PDF artifact."
----
-
-# Report To PDF
-
-Use this skill only when the user explicitly needs a PDF from an existing Data Analytics report, dashboard, or inline chart surface. Prefer a static HTML export or static report file as the source. Do not rely on a live MCP app's direct in-frame print path; Codex MCP apps run in a sandboxed host that does not expose a supported print/PDF bridge.
-
-The expected path is static HTML -> Chrome headless print-to-PDF -> PDF verification. If only a live MCP app report exists, create or retrieve the matching static HTML/export source first.
-
-## 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. Resolve the static source.
-
-   Use an absolute local path to a static HTML report/export or a local URL served from that static export. If the source is a live MCP app, blob stub, sign-in page, redirect page, incomplete viewer, or an app shell that contains boot scripts but not the report content, stop and obtain a static HTML/export source before continuing.
-
-   When the user provides a hosted artifact URL, first determine whether it exposes a usable static export or package source. If the static export is unavailable but the validated artifact payload is still available in the current run, create the matching static HTML/export from that payload and preserve source provenance in the handoff. If neither a static export nor the artifact payload is available, stop with a blocker instead of printing the live app shell or rebuilding the report from memory.
-
-   When creating or repairing the static source, keep visible metadata reader-facing. Do not copy internal artifact runtime fields, package plumbing, or validator/debug state into the report body, header, footer, or source section. For example, omit raw labels such as snapshot status, package path, widget type, manifest path, renderer IDs, validation status, and local temp paths from the visible PDF. If a runtime detail matters for audit or troubleshooting, preserve it in support notes or the final handoff instead of the PDF. Translate data-state caveats into reader language only when they affect interpretation, such as "synthetic demo data" or "partial source coverage."
-
-2. Generate the PDF with Chrome CLI headless print-to-PDF.
-
-   Use the platform-specific Chrome executable available in the environment. Common examples are `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` on macOS and `google-chrome`, `chromium`, or `chromium-browser` on Linux. This is the primary conversion method because it prints the static HTML with a browser rendering engine and usually preserves selectable text, layout, charts, tables, and print CSS.
-
-   ```bash
-   chrome \
-     --headless=new \
-     --disable-gpu \
-     --no-first-run \
-     --no-default-browser-check \
-     --no-pdf-header-footer \
-     --print-to-pdf=/absolute/path/to/report.pdf \
-     /absolute/path/to/report.html
-   ```
-
-3. If Chrome is unavailable or cannot produce a valid PDF, use a renderer-backed fallback.
-
-   Use the next available local mechanism that renders the same static HTML/export source and prints or saves that rendered page to PDF. Keep the fallback tool-agnostic: the requirement is faithful HTML rendering followed by PDF output, not a specific implementation. Do not replace this with a model-authored PDF layout, manually redrawn charts, or a report reconstructed from memory.
-
-   A fallback is acceptable only when:
-
-   - the static HTML/export remains the source of truth
-   - the rendered output preserves the report title, narrative, charts, tables, caveats, and source details
-   - app-only controls are omitted
-   - the resulting PDF passes the same verification checks as the primary Chrome path
-
-   If no available local renderer can print the static HTML/export faithfully, stop and report the blocker with the missing capability and the source file that could not be converted.
-
-4. Verify the PDF itself.
-
-   Confirm page count and metadata with `pdfinfo` or equivalent. Extract text with `pdftotext` or equivalent when the PDF should contain selectable text. Render representative pages with `pdftoppm` or equivalent and inspect them for blank charts, clipped content, missing source details, unwanted controls, internal runtime metadata, and layout regressions. For short reports, render every page. Include a negative check for app-only control labels such as share, edit, refresh, publish, toolbar, menu, and drag affordances, plus internal artifact labels such as snapshot status, widget type, manifest path, package path, validation status, and local temp paths.
-
-5. Repair before handoff.
-
-   If the output is blank, clipped, missing charts, missing source details, or includes app-only chrome, fix the static HTML/export source, print stylesheet, or renderer invocation and regenerate. Do not hand off an unverified PDF unless the user explicitly accepts the limitation.
-
-6. Hand off the PDF.
-
-   Return the PDF path, source HTML path or URL, and verification performed. If the static HTML/export had to be created from an artifact payload because the hosted URL did not expose one, say that briefly. If verification could not be completed, state the gap clearly.
-
-## Standards
-
-- Preserve the reader-facing artifact content: title, narrative, charts, tables, caveats, source details, and generated-at or source freshness details when present.
-- Omit app-only controls: top bars, share menus, edit controls, refresh controls, drag handles, hover-only menus, and interactive-only affordances.
-- Omit internal artifact and conversion metadata from the visible PDF. Do not show raw runtime fields, implementation state, package labels, local paths, validator/debug labels, or status strings that exist only to operate the app or export pipeline. Keep audit-useful internals in support files or the handoff, and use plain reader-facing caveats in the PDF when a data state affects interpretation.
-- Prefer a text PDF with selectable/searchable text. Use a screenshot/image PDF only when a faithful text PDF is not viable, and state that text may not be selectable or searchable.
-- Keep the static source as the PDF source of truth. Do not reconstruct the report from memory when a source HTML/export exists.
-- Do not create a model-authored PDF from scratch as a normal fallback. Direct PDF construction is acceptable only as an explicitly labeled last-resort workaround after the user accepts the quality limitation.
-- Keep generated PDF support files together when possible: static HTML source, PDF output, extracted text, page previews, and any notes about source retrieval or renderer fallback.
-
-## Verification Guidance
-
-Before handoff, verify the PDF with the local tools available in the environment:
-
-- Confirm the PDF exists, is non-empty, and has the expected page count and page size.
-- Confirm text is selectable/searchable when a text PDF is expected.
-- Render or preview representative pages; for short reports, prefer checking every page.
-- Inspect for blank pages, clipped charts, missing tables, missing source details, unwanted app controls, and leaked internal artifact or conversion metadata.
-- If the skill file itself was edited, run the repository's normal markdown or diff checks.
-
-Examples when available: `pdfinfo`, `pdftotext`, `pdftoppm`, file-size checks, and `git diff --check`.

package/template/.codex/skills/data-analytics/skills/build-report/report-to-pdf/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Report To PDF"
-  short_description: "Convert static Data Analytics report exports into verified PDF artifacts"
-  default_prompt: "Convert an existing Data Analytics HTML report or export into a verified PDF artifact."
-policy:
-  allow_implicit_invocation: false

package/template/.codex/skills/data-analytics/skills/build-report/specifications/executive-report.md

@@ -1,97 +0,0 @@
-# Executive Report Specification
-
-Use this specification for `product stakeholders`: product, business,
-leadership, and general stakeholder readers who need a decision-ready narrative rather than a methods memo.
-
-Shared artifact, visualization, layout, citation, and sharing rules live in
-$build-report. This file only captures what is different for the executive shape.
-
-## What This Shape Optimizes For
-
-- Lead with the answer and why it matters.
-- Use plain language and translate jargon before using it.
-- Optimize for decision usefulness over methodological completeness.
-- Show enough evidence to trust the point, but keep supporting mechanics out of the main reading path unless they materially change the takeaway.
-- Integrate implications into the summary, section-level interpretation, and next-step framing rather than isolating them in a standalone section.
-
-## Required Structure
-
-Default to this order:
-
-1. Title
-2. Executive summary
-3. Key findings with visual evidence
-4. Recommended next steps
-5. Further questions
-6. Caveats and assumptions
-
-These entries define section roles, not literal heading text, except that the executive summary must remain a visible section labeled `Executive Summary`. Use story-specific headings for later sections when that reads better. For example, a findings section can be titled `Why concentration increased` instead of the generic `Key findings with visual evidence`.
-
-For most reports, a busy reader should be able to skim the title, executive summary, and first one or two body sections and understand the answer.
-
-## Drafting Rules
-
-- Use a short plain-English title.
-- The executive summary should stand on its own and answer the user's question directly.
-- Render the executive summary as its own visible section immediately after the report title. Do not collapse it into the title block, an unlabeled lede, a subtitle, KPI cards, or bold opening paragraphs.
-- Default to 2-4 executive-summary bullets or short mini-paragraphs. Start each item with a bold topic sentence.
-- The required structure is role-based, not a rigid outline. Headings may be renamed, sections may be combined, and the order may adapt to the story. However, the report should still visibly perform the needed roles: summary, findings, evidence, interpretation, implications or next steps, open questions when useful, and caveats or assumptions.
-- Avoid thin executive reports. A concise report is fine, but it should not leave the reader to infer the meaning of tables or charts. Each major finding should include enough explanation to understand the comparison, magnitude, interpretation, and so-what.
-- Executive reports should be concise in the summary, not compressed in the evidence path. The body must be substantial enough that a reader can audit the conclusion without relying on hidden process notes.
-- Do not open the report with methodology, definitions, or caveat-setting before the answer unless that context materially changes interpretation.
-- Start each major section with the takeaway, not scene-setting.
-- Use rich markdown in the body as well as the executive summary when it helps scanning: bold topic sentences for important paragraphs, render numbered or bulleted recommendations as real lists, and avoid run-on list text in a single paragraph.
-- Use section headings that advance the story rather than copying the template labels verbatim when a more specific heading would read better.
-- For major findings, make the heading the insight, tension, or driver, not a generic topic label. Prefer headings like `Multimodal ARR expanded sharply,
-  but the current run-rate is below the peak` over labels like `Customer and segment drivers`.
-- Keep each section's `so what` explicit. Put it immediately after the evidence when possible.
-- Keep methods brief in the body unless a methodological caveat materially changes the takeaway.
-- Do not include process notes, validator notes, chart-selection rationale, or
-  "why this chart is absent" explanations in the visible report body unless the user explicitly asks for methodology or the detail changes the decision.
-- For diagnostic and strategy reports, do not insert a default KPI-card row or scorecard strip between the title and executive summary.
-- For executive KPI readouts, portfolio scorecards, MBR/QBR-style reports, or one-section-per-business-area reports, include a compact KPI-card strip after the executive summary when headline actuals, deltas, and plan/status signals are available. Do not use a broad summary table as the default substitute for those cards.
-- Use neutral, descriptive visual headers for charts and tables. Keep the narrative claim in the surrounding markdown, not duplicated as the visual title. Prefer visible dates like `May 12, 2026` or `Q2 FY26 to date` over ISO-formatted dates in reader-facing copy.
-- Include next steps and further questions when they help the user act.
-
-If the report is one of these common forms, bias the section framing accordingly:
-
-- KPI readout: bottom line, current state, comparison, status, drivers, risk,
-  next action.
-- Diagnostic memo: what changed, verified drivers, rejected explanations,
-  residual uncertainty, and implications integrated into the summary and major sections.
-- Strategy memo: answer or recommendation, strongest evidence, tradeoffs,
-  caveats, next decision.
-
-## Section Pattern
-
-For each major section:
-
-1. Takeaway headline
-2. More detailed evidence
-3. Visual evidence
-4. Short evidence note or caption
-5. Short implication, next step, or open question when useful
-
-Use the heading to carry the narrative insight. Avoid generic topic headers such as `Segment drivers`, `Customer analysis`, or `Performance trends`.
-
-Do not dump visuals without interpretation. Do not delay the main point behind setup prose.
-
-## Executive QA Addendum
-
-- A first-time reader can skim the title, executive summary, and section headers and understand the answer.
-- The title is short and plain-English.
-- The executive summary uses 2-4 bullets or short mini-paragraphs with bold topic sentences by default.
-- The executive summary does not duplicate itself elsewhere near the title.
-- The body expands the same takeaways from the summary rather than introducing a disconnected second story.
-- The report does not open with methodology, definitions, or caveats before the answer unless that context materially changes interpretation.
-- Implications appear in the summary, relevant sections, or next steps rather than as a standalone block.
-- Citations support trust without interrupting reading flow. If numeric markers like `[1]` or `[2]` are used, they should resolve to linked,
-  human-readable citation metadata and report evidence affordances rather than opaque labels.
-- Every major section answers `so what`.
-- Plain language wins unless a technical term is actually necessary.
-- Diagnostic and strategy reports do not insert a default KPI-card row between the title and executive summary.
-- Executive KPI and portfolio reports use KPI cards for the skimmable top-line status and reserve tables for supporting exact values or audit detail unless the user asked for a table.
-- Visual titles are neutral labels, not insight sentences, and charts use differentiated categorical colors for unrelated entities plus neutral dashed styling for plan, target, forecast, budget, quota, or baseline comparisons.
-- Methods, caveats, and uncertainty are present where needed but do not crowd out the decision story.
-- Report-building decisions and visualization QA details are preserved in source notes or handoff artifacts, not narrated as executive content.
-- Recommendations and implications are clearly signposted and evidence-backed.

package/template/.codex/skills/data-analytics/skills/build-report/specifications/mcp-app-report.md

@@ -1,59 +0,0 @@
-# MCP App Report Specification
-
-Use this when the selected report surface is a bounded manifest/snapshot rendered by the Data Analytics MCP artifact app.
-
-Before creating or revising an MCP app report artifact, read `../../../src/analytics-app-core.md`. It defines the shared dashboard/report artifact contract, bounded snapshot, source safety, runtime behavior, validation helpers, and MCP-specific payload/encoding rules.
-
-## Build Shape
-
-- Define ordered `blocks[]`, `sources[]`, and bounded cards/charts/tables in the manifest. Treat `blocks[]` as the narrative reading path.
-- Set `manifest.title` to the reader-facing title.
-- For MCP app reports, make the first reader-facing block a normal `type: "markdown"` block whose body is a single `#` heading matching `manifest.title`. Do not rely on the app chrome as the report's only visible title.
-- The title block is only the report title. For stakeholder reports, the next narrative markdown block must start with a visible `## Executive Summary` heading before the summary content. Do not collapse the executive summary into the title block or rely on bold opening paragraphs, KPI cards, subtitles, or metric strips to satisfy the executive-summary section role.
-- Use reader-facing headings inside markdown blocks to separate major report segments. Do not rely on chart titles, table titles, or non-rendered metadata as the only visible title for a major segment.
-- Use `type: "metric-strip"` with `cardIds` when a KPI strip is needed; do not create standalone metric blocks.
-- Connect block evidence to source references when the surface supports it, and preserve the full audit trail in source metadata or supporting artifacts.
-- MCP app reports must include at least one native manifest chart block backed by reviewed snapshot data.
-- Default to built-in report artifact blocks for MCP app reports: `markdown`, `metric-strip`, `chart`, and `table`. Use native blocks for ordinary narrative sections, KPI strips, charts, tables, caveats, and source notes instead of hand-authored HTML.
-- Use report chart types supported by the current MCP artifact schema. Keep report interaction bounded; use dashboards, not reports, for filterable exploration.
-- Include report-native visual/table blocks when quantitative evidence is available and useful, not only markdown summaries.
-- Do not render filters or dashboard-style exploration controls in an MCP app report.
-- Metric cards use one `metrics[]` list. The first metric renders as the large value; later metrics render as labeled secondary badges. Each metric declares `label`, `field`, optional `format`, and `signed: true` for signed changes.
-- When a metric label is not self-defining, include a card description or nearby markdown that explains the metric in reader terms, and include the exact calculation in `source.query.metric_definitions`.
-- Percent values rendered with `format: "percent"` or `valueFormat: "percent"` must use the same numeric scale consistently in the provided data. Use decimal rates for computed numeric fields, such as `0.149` for `14.9%`, or pass preformatted reader-facing strings where exact display text matters.
-
-## Source And Data Requirements
-
-- Every native chart and table block must expose provenance through the canonical `source` structure, either directly on the block or by `sourceId` reference to `manifest.sources[]`. Put runnable SQL/code in `source.query.sql`, a human-readable query summary in `source.query.description`, table names in `source.query.tables_used`, material predicates in `source.query.filters`, and metric formulas in `source.query.metric_definitions`. Do not rely on dataset names, source labels, or source order to attach provenance.
-- Do not create artifact `manifest.filters` just to document SQL predicates in a report. Report predicate provenance belongs in `source.query.filters`; `manifest.filters` is only for interactive controls.
-- Every native chart block must be backed by a source dataset that is richer than the chart's visible encodings. Do not create chart datasets or expanded source-data tables with only the plotted fields when the reviewed analysis can expose more context. Preserve useful dimensions, including relevant customer, account, company, segment, and product names, plus time/cohort fields, potential grouping columns, numerator/denominator components, ranks, baselines, comparison periods, and adjacent measures that help the reader audit or re-encode the chart.
-- Retaining a potential grouping column for auditability does not mean the shipped chart should bind it as `encodings.color`, series, or grouped/stacked behavior; only add visible grouping when it is a second categorical dimension beyond the axis category.
-- If a chart must use a minimal dataset because of privacy, query cost, source limits, or metric-definition constraints, record that exception in report source notes or a visible caveat when it affects interpretation.
-- Use `snapshot.accessIssues` only for required report data that could not load, and set the snapshot status to `partial` or `blocked` in those cases. Do not use `accessIssues` for optional source limitations, denied exploratory joins, methodology caveats, or provenance notes in an otherwise ready report; place those in a markdown body block, source metadata, or report notes instead so the artifact does not render a top-of-report blocker.
-
-## Chart And Custom Block Rules
-
-- For chart widgets and native manifest charts, provide the chart family and fields explicitly according to the MCP tool descriptions. Validate before rendering; the app should not choose the first dimension/measure, flip horizontal bar axes, infer grouping fields, or guess units.
-- Use `type: "html"` blocks when the user requests report customization that requires custom rendering, including requests to use Seaborn, Matplotlib, a bespoke visual/layout treatment, or a chart form that cannot be represented with built-in report blocks and native chart/table options.
-- Route custom chart work through `$visualize-data`, generate the chart from the Seaborn templates as a compact Matplotlib SVG, embed it in the HTML block, and document the exception. Keep ordinary narrative, KPI, native chart, table, caveat, and source sections in built-in blocks.
-- Keep custom chart HTML blocks as containers around generated chart images with title, caption, alt text, and source context. Do not ship hand-authored SVG, CSS bars, canvas, or JavaScript as the chart itself.
-- HTML blocks auto-size to their content; inspect the rendered artifact for clipping, missing images, and collisions with nearby blocks before handoff.
-- MCP report chart cards and detail pages should share the same native renderer and chart-type compatibility logic. Do not embed the standalone inline chart widget or rebuild a separate detail-page chart implementation.
-- Do not emit inline MCP chart or table widgets during report-mode work, and do not treat inline MCP chart/table widgets as report visuals or evidence previews. Report charts, tables, and previews must live in the selected report surface and be backed by reviewed snapshot data or static PNG assets.
-
-## Revision And Rendering
-
-- When modifying an existing MCP app report, update the complete manifest and bounded snapshot from the previous full artifact. The revised artifact must contain all unaffected report parts exactly as before, plus only the requested addition or modification. Validate and render that full artifact; never replace a full report with an excerpt, follow-up card, or abbreviated report unless the user explicitly asks for a separate slim version.
-- Validate with `validate_artifact` before the first visible `render_artifact` call. Fix validation errors with the validator only; do not use the visible renderer as an iterative validator.
-
-## Hosted Sharing
-
-- The artifact app's `Share` menu may offer `Publish to Sites` for publishing the current report or dashboard through Site Creator.
-- Treat hosted sharing as agent-mediated production publishing. The artifact UI should launch a Codex follow-up; it should not directly call Site Creator, hold deployment credentials, or mutate production access from the browser.
-- Before publishing, call `export_artifact_package` on the validated current artifact payload. The exporter materializes a Cloudflare Worker-compatible Site Creator package using the real MCP artifact runtime and serves the report data through `/api/manifest`, `/api/snapshot`, `/api/package`, `/api/source-file`, and `/api/inline-chart-widget`. Do not deploy a viewer that depends on MCP-only `window.openai.toolOutput` state, and do not hand-roll a standalone HTML renderer.
-- Hosted Site Creator exports are reader surfaces by default. Hide artifact editing controls and remove `Publish to Sites` from the hosted export menu; revise the MCP artifact and redeploy a new version when shared content needs to change.
-- Preserve the current manifest, bounded snapshot, inline-safe source text, package metadata, reading order, visuals, tables, source details, and narrative.
-- Keep static HTML and PDF exports content-only: include the report title, narrative, visuals, tables, and source details, but omit the interactive top bar and app-only controls.
-- Use the `sites-hosting` workflow for project resolution, local validation, source provenance, artifact preparation, version creation, deployment polling, and access control.
-- Use only the explicitly selected hosting audience; missing audience does not authorize workspace-wide access. Report the production URL and the configured access mode.
-- If the local report package files or validated artifact payload are unavailable, stop and ask for the missing source instead of publishing an empty, fallback, or stale report.

package/template/.codex/skills/data-analytics/skills/build-report/specifications/technical-report.md

@@ -1,75 +0,0 @@
-# Technical Report Specification
-
-Use this specification when the user explicitly wants a technical audience or when the report is primarily about data methodology, measurement design,
-statistical analysis, experimentation, modeling, or other audit-heavy work.
-
-Shared artifact, visualization, layout, citation, and sharing rules live in
-$build-report. This file only captures what is different for the technical shape.
-
-## What This Shape Optimizes For
-
-- Lead with the main result, then show the definitions, evidence, methods, and limitations needed to trust it.
-- Preserve technical precision. Simplify wording only when meaning is unchanged.
-- Define metrics, cohorts, filters, baselines, and units before leaning on them in argument.
-- Keep assumptions, uncertainty, and failure modes close to the findings they affect.
-- Distinguish descriptive, diagnostic, inferential, predictive, and causal claims.
-- Integrate implications into the technical summary, section-level interpretation, and next-step framing rather than isolating them in a standalone section.
-
-## Required Structure
-
-Default to this order:
-
-1. Title
-2. Technical summary
-3. Key findings with visual evidence
-4. Scope, data, and metric definitions
-5. Methodology
-6. Limitations, uncertainty, and robustness checks
-7. Recommended next steps
-8. Further questions
-
-These entries define section roles, not literal heading text. Use headings that fit the actual result and method story instead of copying the template labels verbatim.
-
-If the work is model-heavy, experimental, or inferential, add a dedicated section for model specification, experimental design, or validation details instead of hiding them inside footnotes.
-
-## Drafting Rules
-
-- The technical summary should stand on its own and state the main result directly.
-- Start sections with the result, not with methodology setup.
-- Use section headings that reflect the actual result or method question rather than copying the template labels verbatim when a more specific heading would improve readability.
-- For major findings, make the heading the substantive result or driver, not a generic topic label. Prefer headings like `Digital Natives and Startups drove most of the segment expansion` over labels like `Customer and segment drivers`.
-- Define uncommon or overloaded terms on first use.
-- Make definitions, cohorts, denominators, and comparison baselines explicit before the reader needs them.
-- If a claim depends on modeling choices, thresholds, priors, sampling rules,
-  or feature engineering, say so explicitly.
-- Include negative results, counterexamples, sensitivity, or failure modes when they change interpretation.
-- Use top-line metrics only when each one adds analytical value.
-- If the work builds a model, keep fitting, diagnostics, and interpretation in the companion notebook unless a reusable support module is clearly necessary.
-- Recommendations or next steps should follow from the evidence, not from generic best practice.
-
-## Section Pattern
-
-For each major section:
-
-1. Result headline
-2. Precise interpretation
-3. Visual evidence
-4. Evidence note with definition or sample context
-5. Method or assumption note when needed
-6. Limitation, implication, or open question
-
-Use the heading to state the result the section proves. Avoid generic topic headers such as `Segment drivers`, `Customer analysis`, or `Performance trends`.
-
-Do not separate results from the definitions or assumptions needed to trust them. Do not open with methods text that delays the result.
-
-## Technical QA Addendum
-
-- A first-time technical reader can audit the logic without guessing what was measured or how.
-- The technical summary and body tell the same story at different depth.
-- Definitions, cohorts, denominators, and baselines are explicit.
-- Each major section clearly distinguishes result, evidence, and limitation.
-- Implications appear in the summary, relevant sections, or next steps rather than as a standalone block.
-- Uncertainty is quantified when possible and described precisely when not.
-- If the work includes forecasting, experiments, causal claims, or modeling,
-  the report states what the result does and does not establish.
-- Recommendations and implications remain clearly signposted and evidence-backed.

package/template/.codex/skills/data-analytics/skills/design-kpis/SKILL.md

@@ -1,103 +0,0 @@
----
-name: design-kpis
-description: "Define KPI frameworks, targets and measurement plans. Use metric-diagnostics to explain an existing metric change."
----
-
-# Design KPIs
-
-Design KPI frameworks, set targets, and develop measurement plans that help teams make product or business decisions.
-
-## 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.
-
-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.
-
-## Workflow
-
-### 1. Clarify The Decision And Operating Context
-
-Understand the decision the metrics need to support, the context in which they will be reviewed, and who will act on the result. Ask the user to clarify the goal, operating cadence, or measurement constraints when missing or ambiguous input would change the recommendation.
-
-### 2. Gather Evidence Before Recommending Metrics
-
-When the prompt does not already provide enough context to know what success means, gather that context before recommending metrics or targets. Use $gather-business-context to understand the goal, current state, audience, constraints, risks, existing definitions, prior decisions, and any baseline or target context that should shape the metric system.
-
-For KPI design, use that context to clarify what success is meant to mean, how related metrics have been defined before, and which constraints or risks should affect the recommended KPIs, drivers, guardrails, or measurement plan.
-
-### 3. Generate A Wider Candidate Set
-
-Create candidate outcome, driver, and guardrail metrics before narrowing.
-Each candidate should have a clear definition and a plausible link to the decision. Use the example metric shapes below as inspiration when helpful, not as a required template.
-
-### 4. Compare And Select Metrics
-
-Compare candidate metrics by whether they:
-
-- reflect the goal: the metric should represent the intended outcome. When using a proxy, explain why it should reflect real progress and where it could mislead.
-- inform a real decision: movement should change what the team does, prioritizes, or investigates.
-- show useful signal at the decision cadence: a metric can be conceptually good but too slow-moving or noisy for the decision it supports. For example, annual retention may be the right outcome, but it may not help a weekly launch review unless paired with earlier indicators.
-- can be influenced by the team: the team should have plausible levers, or the metric should be paired with drivers it can affect.
-- can be measured operationally: the team should be able to instrument, calculate, and track the metric consistently without one-off manual work.
-- are hard to improve in a misleading way: improving the metric should not obviously hide harm to quality, trust, retention, cost, or another important outcome.
-
-Use lightweight scoring only when it helps explain tradeoffs. Recommend `1-3` primary KPIs, `1-2` driver metrics for each KPI when they improve diagnosis, and `1-2` guardrails when tradeoffs are likely. Do not recommend extra metrics unless they materially improve decision-making.
-
-For each recommended metric, include enough detail for the team to use it: what it measures, why it matters, how it is calculated, where it comes from, its main pros and cons against the selection criteria above, and what caveats or guardrails matter.
-
-### 5. Set Targets When Needed
-
-Treat target setting as a separate judgment from metric selection. First decide what should be measured; then set targets when the user asks or when the recommendation needs a threshold to be useful.
-
-Use the target-setting approach that best fits the evidence:
-
-- Top-down: start from benchmarks, historical performance, comparable products, competitor or market context, or a reasoned view of what good would need to look like for the decision.
-- Bottom-up: start from what the team can realistically do, such as what is shipping, how adoption is expected to build, or which operating levers should move the metric.
-
-Use data to set or evaluate targets. Once the target-setting approach is clear, identify what data it requires, such as provided inputs, internal performance data, external benchmarks or market data, and results from similar past work.
-
-Compare aspirational targets with what the team can realistically influence through planned work, available audience, expected adoption, and historical movement. A good target should be meaningful for the decision and plausible enough to guide action. Explain the target anchor, key assumptions, and confidence. If the strongest target-setting method requires missing inputs, share the methodology and ask whether the user can provide or identify the relevant data. If there is still enough evidence for a directional target, present it as a provisional range; otherwise recommend the measurement needed before setting a firm target.
-
-### 6. Deliver The Recommendation
-
-Keep the final recommendation concise and decision-oriented. Use $build-report when the user asks for a polished artifact; otherwise return a compact metric-design brief with:
-
-1. initiative summary
-2. recommended metric candidates, with definition and rationale
-3. target recommendation, if included, with anchor, assumptions, and methodology
-4. evidence reviewed
-5. assumptions and missing context
-6. risks and guardrails
-7. open questions
-
-## Example Metric Shapes
-
-Different contexts need different metric shapes. Use these as examples, not a template:
-
-- Product launch or adoption: pair an outcome metric for adoption or value realization with drivers for activation, engagement, repeat use, or time to value, plus guardrails for experience quality.
-- Growth work: choose the business outcome the team is trying to improve, such as activation, retention, or monetization; add drivers that explain how growth is expected to happen and guardrails for quality.
-- Funnel work: choose the progression or completion outcome that represents success; add drivers around where people advance or drop off and guardrails for downstream quality.
-- Operating review: focus on health, pacing, and action-oriented metrics that show whether the business is on track and where attention is needed.
-- Experiment or intervention: use one primary success metric tied to the decision, diagnostics that explain movement, and guardrails for unintended effects.
-- Data, model, or analytics initiative: connect technical performance to the decision or workflow it improves, with adoption, reliability, cost, or fairness guardrails when relevant.
-- Platform, reliability, or operations work: measure service health, throughput, quality, cost efficiency, and customer impact in terms the owning team can act on.

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

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Design KPIs"
-  short_description: "Define KPIs, driver metrics, guardrails, and scorecards"
-  default_prompt: "Design a KPI framework with primary metrics, drivers, guardrails, targets, and reporting guidance."
-policy:
-  allow_implicit_invocation: true

package/template/.codex/skills/data-analytics/skills/gather-business-context/SKILL.md

@@ -1,68 +0,0 @@
----
-name: gather-business-context
-description: "Find missing business or metric context in provided or connected sources before dependent analysis."
----
-
-# Gather Business Context
-
-Use this skill to collect the business context needed to understand an analytical question before doing deeper work. Focus on what the topic is, why it matters, what changed or is being decided, who or what source is closest to the work, and which definitions or artifacts should frame the analysis. This is a retrieval and extraction skill: gather enough context to set up the next step, not a final report, root-cause analysis, or broad background scan. Skip it when the prompt already provides the needed context or the task is fully self-contained.
-
-## 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. Identify The Retrieval Target
-
-Establish the analytical topic that needs context and why it matters for the next step. Capture the boundary needed to search and interpret sources, such as the relevant product area, audience, time period, or decision. If the timeframe is missing, use the narrowest reasonable window implied by the task and label it as an assumption.
-
-### 2. Build Search Anchors
-
-Search with concrete identifiers rather than broad topic guesses. Start with the names the user provided or the sources surfaced, then expand with adjacent terms that help recall, such as aliases, owners, teams, dates, source names, related entities, or entities found in earlier results.
-
-Start broad enough to avoid missing relevant context. If too much comes back and a quick scan suggests the results are mostly unrelated, combine anchors to narrow retrieval, for example a metric plus a dashboard name, a feature plus a launch window, or a customer plus the relevant workflow. If a likely source comes back thin, revise the anchors before treating the source as missing.
-
-### 3. Search From Discovery Points Toward Authoritative Artifacts
-
-Before searching deeply, identify the enabled or provided source families likely to contain useful context for the task. Start from saved user-context and semantic-layer anchors when they exist, then make a focused pass across the relevant connected or provided apps when they can establish current definitions, decisions, source-of-truth context, or useful verification. Do not search every connector by default, but do not stop after one good source when another likely source could add useful detail.
-
-Within those source families, start where the task is most likely to reveal useful context or links, such as a source named by the user, a report or dashboard, a planning document, a work tracker, or an owner discussion. Follow linked artifacts instead of stopping at the first mention, and use discovery sources to move toward artifacts closer to what was decided, defined, put into practice, or measured.
-
-### 4. Extract Only Decision-Shaping Context
-
-Treat business context as a fixed extraction target, not an open-ended summary. Capture the facts that will shape the downstream analysis: the topic's business meaning, why it matters now, how it is defined or measured, where to verify it, what recently changed, and what uncertainty should travel with the analysis. Examples can include a metric definition, current rollout state, dashboard link, owner note, source conflict, or stated next step.
-
-Keep the context note focused on details that help frame the next analysis. Skip broad background, adjacent history, or long source excerpts unless they add useful context.
-
-### 5. Keep Source Notes Compact And Attributable
-
-For each useful source, record enough attribution for the downstream work to be checked later: when the source applies, what kind of source it is, what factual context it established, and any important caveat or conflict. Distinguish source facts from inference and do not imply source review, stakeholder views, metric certainty, or confidence beyond what was actually established.
-
-### 6. Reconcile Conflicts Explicitly
-
-When sources disagree in a way that could change the downstream framing, preserve the disagreement instead of smoothing it over. Prefer the newest explicit decision artifact over older plans, owner-written docs over third-party summaries, and implementation artifacts over aspirational plans when the question is what is live, shipped, logged, or queryable now. Treat an informal source as stronger than a canonical artifact only when it clearly records a later decision or owner confirmation.
-
-If disagreement remains, present both views, label the conflict, and state what source or owner would resolve it. If context is stale or incomplete, say what is missing and where to look next.
-
-### 7. Stop Once The Framing Is Sound
-
-Stop gathering context when the downstream task can be framed well enough to proceed and the likely enabled or provided source families have been checked, ruled out as unavailable, or identified as too thin. Before stopping, make sure the next step has a clear enough understanding of the topic, why it matters, where the important definitions came from, what recent context applies, and what gaps remain.
-
-Continue searching when a relevant enabled or provided source is likely to add useful context. If an expected source was not found, name that as a gap rather than implying it does not exist.
-
-### 8. Return A Lightweight Context Note When Useful
-
-Prefer a focused context note over a full report or raw retrieval dump. Include enough context for the next analysis to proceed without redoing the search: a short summary, the relevant context, important definitions or source links, uncertainty or caveats, and citations. Keep it readable, but do not compress away details that explain the framing or source quality.
-
-If the user asked only for quick orientation, shorten the structure while preserving citations, conflicts, and missing canonical artifacts.
-
-## Standards
-
-Judge sources by what they can actually establish. Informal discussion can be useful for discovery and recent context, but durable artifacts are usually stronger evidence for definitions, decisions, status, and measured results once found. Prefer sources close to the work, recent enough to reflect current reality, and explicit about what they establish. Surface missing source-of-truth artifacts as context gaps.
-
-Keep important claims attributable. Treat a source as useful only when it clarifies how the downstream task should be framed or interpreted; sources that merely mention the topic are incidental. Preserve enough evidence to check the work later, and label interpretation, assumptions, conflicts, and uncertainty when support is thin, stale, indirect, or conflicting.
-
-Preserve disagreements that could change the framing. Prefer owner-authored or decision-adjacent material and evidence of what is current over secondhand summaries or speculation. Do not infer consensus from silence. Say what source or owner would resolve an important conflict.

package/template/.codex/skills/data-analytics/skills/gather-business-context/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Gather Business Context"
-  short_description: "Collect product and business context before analysis"
-  default_prompt: "Gather the product and business context needed to frame this analysis accurately."
-policy:
-  allow_implicit_invocation: false