create-yss-spec 3.5.0 → 3.5.3

package/template/.codex/skills/data-analytics/skills/build-dashboard/specifications/streamlit-dashboard.md

@@ -1,85 +0,0 @@
-# Streamlit Dashboard Specification
-
-Build Streamlit dashboards as real apps: summary-first, interactive, and fast enough for repeated filter changes. Keep the result chart-led, simple to operate on first load, and clear about what the viewer should do next.
-
-Use the shared `build-dashboard` brief first to lock the audience, KPI,
-filters, and main questions the app should answer. This specification is for implementing the app once Streamlit is the chosen delivery mode.
-
-## When To Use
-
-- The user explicitly wants a Streamlit dashboard or app.
-- The dashboard needs custom interactivity, stateful workflows, or reviewer-style controls.
-- The solution needs Python-side transforms, file inputs, or multiple data sources.
-- The user wants version-controlled app code rather than BI configuration.
-
-Avoid Streamlit when the user explicitly wants an MCP artifact dashboard or a BI platform dashboard.
-
-## Quick Start
-
-1. Start from a clear dashboard brief: audience, primary KPI, default filters, and the key questions the app should answer.
-2. Decide whether the deliverable is local-only code or a live shared app.
-3. Default to one entrypoint and one page unless multiple pages clearly improve the workflow.
-4. Run the app with `streamlit run ...` before treating the task as complete.
-
-## Structure The App
-
-Call `st.set_page_config(...)` near the top of the main entrypoint.
-
-Keep the layout summary-first:
-
-- Hero metrics or KPI cards first.
-- Trend section next.
-- Diagnostic breakdowns below that.
-- Detailed tables or record-level views near the bottom or behind explicit drill-down actions.
-
-Put global filters in the sidebar or a top control row. Keep one clear narrative per page before adding tabs or multipage navigation.
-
-## Implement
-
-Keep page code thin:
-
-- Move data fetching, query code, and expensive transforms into helper functions or modules.
-- Use `st.cache_data` only for deterministic reads or transforms.
-- Keep `st.session_state` focused on UI state and user selections.
-- Favor bounded default queries and lazy-load heavy detail views.
-- Make loading, empty, and error states visible.
-- Keep chart titles concise and labels explicit.
-
-For charts and interactivity:
-
-- Favor the simplest chart library that produces clear interactive charts.
-- Choose chart and table renderers that match the runtime environment. Some Streamlit surfaces, such as Altair-backed charts and `st.dataframe(...)`, can pull in Arrow or `pyarrow` at render time. If the environment cannot reliably satisfy native Arrow dependencies, prefer Plotly for charts and simpler table surfaces such as `st.table(...)` or bounded HTML tables.
-- Use KPI cards for headline values and charts below them for explanation.
-- Keep number formatting consistent across axes, labels, legends, and tooltips.
-- Prefer charts over text blocks, and prefer direct labels over long legends when practical.
-- If the app adds new plotting or data-access dependencies, update the project's dependency declarations and confirm the app still installs and runs cleanly in the target environment before handoff.
-
-## Making It Live
-
-Do not assume deployment is part of the ask. Many Streamlit tasks only need local app code and a smoke-tested run command.
-
-If the user wants a live shared app, identify all of the following before treating the app as done:
-
-- Hosting target
-- Auth model
-- Network access to the data backend
-- Secrets and environment variables
-- Dependency installation path
-- Start command
-
-Keep local development commands and deployment assumptions explicit so another engineer can reproduce the app.
-
-## Validate
-
-Run the closest realistic smoke test:
-
-1. Launch the app locally with `streamlit run path/to/app.py`.
-2. Exercise the main filters, tabs, upload flows, or drill-down actions.
-3. Confirm the default page state is useful before any clicks.
-4. Confirm reruns do not raise runtime exceptions or trigger obviously wasteful reloads.
-5. Check that the layout still reads clearly on desktop and narrower widths if the app will be shared broadly.
-6. Verify loading, empty, and error states are understandable.
-
-Do not stop at "the app booted." Validate at least one real chart render path and one detail or table render path, because renderer-specific dependency failures can appear only after the page starts drawing data-backed components.
-
-When Streamlit UI behavior is hard to unit test, prefer validating extracted helper functions plus a local manual smoke test.

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

@@ -1,207 +0,0 @@
----
-name: build-report
-description: "Create a source-backed analytical report with findings, charts, caveats and delivery checks."
----
-
-# Report Building
-
-Use this skill when the user needs a durable analytical report rather than a dashboard, notebook-only dump, or transient chat summary. The report owns the reader-facing narrative, audience shape, evidence placement, visual/table placement, caveats, source metadata, and handoff. The underlying analysis should still come from the appropriate analysis, notebook, data quality, diagnostics, KPI, or product-analysis workflow.
-
-If this skill is selected directly or included by a report-mode workflow, the run is incomplete until the selected report surface exists or a concrete blocker is recorded. Do not finalize with chat-only prose, an inline widget, a local URL, or an ad hoc artifact that skips the report shape. Treat inline summaries and notebook outputs as progress evidence, not as substitutes for the report. Once this skill is selected, reserve charts, tables, and previews for the selected report surface. The absence of the word "report" is not a waiver when an upstream workflow has already classified the task as report mode or when the requested deliverable is a durable analytical answer.
-
-## 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.
-
-Choose exactly one report delivery mode for each run:
-
-- `mcp-app`: a Data Analytics MCP artifact app report. This is the default for safe, bounded in-Codex reports.
-- `html`: a portable static HTML report. Use this when the user asks for HTML, file/blob sharing, Docs/Slides conversion, offline portability, no MCP app/widget rendering, or when the MCP artifact renderer is unavailable, unsafe, or over bounds.
-
-Select exactly one delivery mode per run. Do not build an MCP app report and a static `report.html` as parallel outputs unless the user explicitly asks for a second delivery mode as a separate follow-up. For HTML reports, charts must be static PNG images generated from the Seaborn template workflow and embedded in the HTML. Do not replace those charts with interactive, app-specific, inline SVG, or hand-authored HTML/CSS chart primitives.
-
-## Workflow
-
-1. Define the reporting job.
-
-   State the user question, decision or action the report should support, primary audience, scope, time frame, comparison baseline, success criteria, and what would make the report decision-useful. Choose exactly one audience:
-
-   - `product stakeholders`: default for product, business, leadership, strategy, diagnostics, KPI readouts, and general stakeholder reports.
-   - `technical`: only when the user asks for a technical or methods-first report, or when the report's main value is methodology such as metric definitions, measurement design, statistics, modeling, experimentation, or validation.
-
-   If the work is unusually methodology-heavy but the user did not ask for a technical audience, ask before switching.
-
-2. Read the matching audience specification.
-
-   Read exactly one matching audience specification before gathering evidence, shaping the report spine, or drafting the report surface:
-
-   - [executive-report.md](specifications/executive-report.md) for `product stakeholders`
-   - [technical-report.md](specifications/technical-report.md) for `technical`
-
-   Treat the selected audience specification as a report-quality contract, not as a replacement for the workflow below. Capture its `Required Structure` entries in the report plan or supporting source notes, and stop with a blocker if the matching specification cannot be read.
-
-3. Gather and bound the evidence.
-
-   Inventory the source data, metric definitions, denominators, assumptions, requested cuts, caveats, notebooks, SQL, scripts, query permalinks, source documents, and reviewed datasets needed to support the report. Resolve ambiguities before drafting claims. If a requested metric or cut cannot be supported, record why and state what evidence would be needed to add it. Preserve process notes, source inventory, and reproducibility notes in source metadata, source notes, or supporting artifacts, not in the visible report body.
-
-4. Distill the report spine.
-
-   Before choosing a delivery surface, write or mentally verify a compact answer-first report spine with these entries:
-
-   - question
-   - decision-useful answer
-   - metric, cohort, denominator, time window, and comparison basis
-   - findings by requested segment or driver, with supporting evidence
-   - sensitivity or validation checks when the answer is comparative, causal-adjacent, or surprising
-   - caveats that could change interpretation
-   - recommended next step, monitoring point, or open question
-
-   Ensure report segments are clearly separated and duplicate feature/metric coverage is removed. Each major segment should have one clear job in the report and should pair a claim with evidence, interpretation, and a concrete implication.
-
-   If the spine has only a title, an executive summary, and one chart or table, stop and expand the evidence path before rendering unless the user explicitly asked for a brief.
-
-5. Plan the reader-facing structure.
-
-   Draft the ordered major segments, visible segment titles, and intended evidence format for each segment before building the surface. Use visuals by default for quantitative findings when real data is available; use tables for exact lookup, audit detail, or cases where a chart would obscure the point. If a quantitative segment has no visual, record the omission reason in source notes or supporting artifacts.
-
-   Every planned major segment must have a reader-facing title that will appear in the final report. Do not rely on chart headers, table titles, or non-rendered structure alone to carry the section title.
-
-   Apply the report depth gate before building:
-
-   - The executive summary does not count as the evidence section.
-   - A report with quantitative findings must include visible metric/cohort definitions before those definitions are needed to interpret the evidence.
-   - A comparative report must include segment-level interpretation, not only aggregate values.
-   - A causal-adjacent or behavior-difference report must include at least one validation, sensitivity, or limitation note near the finding it qualifies.
-   - A report with only one narrative block plus chart/table evidence is too thin unless the user explicitly requested a brief, an inline answer, or a single-chart readout.
-
-6. Apply report standards and audience requirements.
-
-   After the general structure exists, apply the relevant standards in this skill. Map each planned major segment to the selected audience specification's `Required Structure` entries, and record any merged, renamed, reordered, or omitted entry with a reason.
-
-7. Design visuals and tables.
-
-   Route every report visualization through `$visualize-data` for chart selection, chart contract, and final-context QA. Keep chart-selection rationale, validator notes, and QA details in working notes, source notes, or supporting artifacts unless the user asks for methodology or the detail changes the reader-facing takeaway. Make sure every visual or table supports a specific report claim rather than existing as decorative context. Plan an adjacent explanatory paragraph for every visualization before rendering. Reserve chart, table, and preview output for the selected report surface.
-
-8. Choose and build one delivery surface.
-
-   Use the single delivery mode selected after the report spine and evidence plan are clear. Do not add a second mode unless the user explicitly asks for it as a separate follow-up.
-
-   Build the selected surface so it preserves the report reading path, visible titles, evidence order, caveats, and source metadata. Use the delivery-mode specifications in `Report Standards` as implementation guidance for the selected surface, not as a substitute for the report-building workflow.
-
-   If the user asks to share an MCP app report or dashboard as a hosted link, use the artifact app's Site Creator share path after the MCP app is valid. Call `export_artifact_package` to materialize the current manifest, bounded snapshot, package metadata, inline-safe source text, and real MCP artifact runtime into a Site Creator-compatible app; do not hand-roll standalone HTML or publish a viewer that depends on MCP-only host payload state. Follow the `sites-hosting` workflow and use the audience explicitly selected by the user; if unset, keep the report local/private and ask only when sharing is required.
-
-   When revising an existing report, treat the current rendered report and source metadata as the starting artifact. Preserve every existing section, visual, table, source, dataset, title, and caveat exactly unless the user explicitly asks to change it or the requested edit makes a narrow dependent update unavoidable. A request to add a section, swap a chart, restyle a visual, or customize one part of the report is not a request to summarize, replace, reorder, or drop the rest of the report. Render the full revised report in the selected surface; do not hand off a section-only, slimmed, or partial replacement artifact when the prior report was complete.
-
-   For correction passes after a validation or rendering issue, patch the previous full report artifact in place. Limit changes to the affected visual, table, section, dataset, or source plus any directly dependent references. Preserve unrelated ids, reading order, narrative text, caveats, recommendations, source metadata, package metadata, and datasets unchanged when the selected surface exposes those concepts. Before rendering, compare the old and new artifact structures and confirm that only the intended parts changed. If the previous full artifact is not available, stop and surface that blocker instead of rebuilding a shorter replacement from memory.
-
-9. Validate the finished report.
-
-   Review the rendered report itself, not just its source files. Confirm that:
-
-   - the top of the report answers the user directly
-   - every major segment has a visible title
-   - claims, visuals, tables, caveats, and implications appear in the intended reading order
-   - the selected delivery surface satisfies its mode-specific standards
-   - the supporting evidence and source notes are sufficient for auditability
-
-   Fix the report before handoff when any of these checks fail.
-
-10. Hand off the selected report.
-
-   Lead with the selected report artifact result or blocker. Then list only the relevant MCP app artifact or HTML report path, plus supporting source, SQL, code, notebook, and chart artifacts. Self-audit the report against the quality bar before handoff. If HTML sharing or conversion is needed and safe, resolve the presentation surface; otherwise record why sharing was unsafe, unavailable, or explicitly waived. Do not substitute a chat summary for the report.
-
-## Report Standards
-
-### PDF Export Specifications
-
-When the user asks to export a Data Analytics report, dashboard, or inline chart surface to PDF, use `report-to-pdf`. That sub-skill owns PDF conversion mechanics so this root workflow stays delivery-mode neutral.
-
-### MCP App Report Specifications
-
-Read [mcp-app-report.md](specifications/mcp-app-report.md) when the selected report surface is an MCP app report. That file owns MCP app report mechanics so this root workflow stays delivery-mode neutral.
-
-### HTML Report Specifications
-
-- Use HTML mode when the user asks for HTML, file/blob sharing, Docs/Slides conversion, offline portability, or when the MCP artifact renderer is unavailable, unsafe, or over bounds.
-- Preserve the shell templates' `data-contract-section` attributes from `assets/executive-report-shell.html` or `assets/technical-report-shell.html`.
-- Generate `report.html` plus PNG chart assets from the Seaborn template workflow. HTML report charts use the Seaborn template workflow and embed generated PNG files; SVG may remain as a supporting source artifact, but the delivered HTML should embed PNG charts. Inspect those image assets before delivery.
-- Keep the HTML reading path report-like: answer first, visible segment titles, evidence and interpretation together, caveats where they matter, and source metadata preserved without appending a visible sources, notes, or reproducibility appendix unless the user explicitly asks for it.
-- Before handoff, inspect `report.html` and the generated PNG chart assets. Use `report-to-google-doc` or `report-to-google-slides` only with HTML reports, not live MCP app reports.
-
-### Narrative
-
-- Every report must have a short plain-English reader-facing title. For HTML reports, use the same title in the document title and visible page header. For MCP app reports, follow [mcp-app-report.md](specifications/mcp-app-report.md).
-- Do not duplicate the title or executive summary in an unlabeled subtitle, lede, scope line, or second summary block.
-- Treat the report title and executive summary as separate visible elements. The report title is the artifact-level name; it does not satisfy the executive-summary section role. For stakeholder reports, render a visible `Executive Summary` section heading immediately after the title before the summary content.
-- Open stakeholder reports with an executive summary that answers the user's question directly. Default to 2-4 bullets or short mini-paragraphs with bold topic sentences.
-- Open technical reports with a technical summary that states the main result, then provide definitions, methods, uncertainty, and limitations needed to trust it.
-- Start major report segments with the takeaway, not setup prose. Use headings that carry the insight rather than copying generic labels.
-- Include visible titles for every major report segment in every delivery mode. Titles are part of the reader-facing report contract, not just private metadata. In HTML reports, render titles as heading elements inside sections. For MCP app reports, follow [mcp-app-report.md](specifications/mcp-app-report.md). Use story-specific titles such as "API ARR is pulling ahead of plan" rather than generic labels when the evidence supports it.
-- Keep an obvious top-to-bottom report reading path. Do not turn a report into a dashboard grid unless the user asked for a dashboard. Use a single-column document flow by default; half-width visual blocks are acceptable only when labels, series, and interpretation remain readable in the selected surface.
-- Use report markdown blocks for narrative insights and interpretation. Keep chart/table headers neutral, and put takeaways in adjacent narrative blocks rather than hiding the argument inside visual metadata. Markdown blocks are the primary place for the story.
-- Reports should be substantial enough to stand on their own. Do not deliver a report that is mostly a chart/table bundle with a short summary. The reader should be able to understand the answer, evidence, interpretation, caveats, and recommended next step from the narrative itself.
-- Use flexible section names and story-specific ordering, but make sure the report still does the core jobs: answer the user's question directly; explain the metric, cohort, denominator, time window, and comparison basis when they affect interpretation; pair each important number or visual with plain-language interpretation in the user's language; explain why the finding matters for the decision; state what remains uncertain or could change the conclusion; and include a practical next step when the evidence supports one.
-- Use rich markdown beyond the executive summary when it improves scanning:
-  bold topic sentences in important body paragraphs, keep recommendations as real markdown lists, and avoid collapsing list items into run-on paragraphs.
-- When using ordered or unordered lists, put each item on its own Markdown line. Do not put `1.`, `2.`, and `3.` items in the same paragraph, and do not leave an intended list item as an unnumbered continuation line.
-- For executive, strategic, and diagnostic reports, the first narrative content after the title should be the executive summary. Do not insert an unlabeled lede, duplicate summary, methodology block, caveat section, KPI strip, or metric card row before the summary.
-- For diagnostic and strategy reports, do not insert a default KPI-card row before the executive summary. KPI, portfolio, MBR/QBR, and one-section-per area reports may use a compact KPI-card strip after the summary when headline actuals, deltas, and status signals are available.
-- Do not use a broad comparison table directly beneath an executive summary as the primary summary artifact for KPI, portfolio, or multi-area reports. Use metric cards for skimmable top-line status when headline actuals, deltas, and status signals are available; use tables for supporting exact values or audit detail.
-- Metric cards should put the headline value first and render supporting measures as labeled secondary context.
-- Percent values must use a consistent numeric scale in the selected surface.
-- Every major report segment should pair a claim with evidence and interpretation, then answer "so what" with an implication, risk, opportunity, recommendation, monitoring point, or next action.
-- Include recommended next steps when the evidence supports action. If the evidence only supports monitoring, say what should be monitored and why.
-- Include further questions when meaningful uncertainty, missing evidence, or follow-up analysis could change the decision. Omit the section only when there are no decision-relevant open questions, and record that choice in source notes.
-- Caveats and uncertainty should be visible where they change interpretation, without crowding out the answer.
-
-### Evidence And Sources
-
-- Base every major claim on saved data, code, query results, notebook outputs, source documents, or rendered charts created or inspected during the task.
-- Tie important numbers, charts, and recommendations to readable source metadata near the relevant paragraph or visual when the selected surface supports it.
-- Keep raw paths, notebook locations, temp directories, request IDs, table names, and implementation-facing audit details in source metadata, source notes, or supporting artifacts unless needed for trust.
-- Do not add a visible bottom sources, notes, or reproducibility section unless the user explicitly asks for that methods layer.
-- Preserve source datasets, query or transformation artifacts, rendering code, output folders, assumptions, omitted metrics, and chart QA notes in source metadata, source notes, or supporting artifacts even when they are not visible in the report body.
-- Surface enough evidence affordance for audit without creating a heavy visible claim graph. Prefer block-level source references when the surface supports them.
-
-### Visuals And Tables
-
-- Report visual headers should be neutral: chart/table name plus a short description only when needed for metric, denominator, cohort, filter, or time window. Put narrative insights and caveats in adjacent markdown blocks.
-- Every report visualization must have an adjacent explanatory paragraph immediately before or after it in the reading flow. The paragraph should state the takeaway, how to read the visual, and the implication or caveat needed to interpret it; chart titles, subtitles, captions, metric cards, or table headers do not satisfy this requirement by themselves.
-- Chart and table subtitles should add a reader-facing insight or interpretive context that the title does not already cover. Prefer direction, magnitude, inflection, rank, comparison basis, scope, time period, unit of measurement, filters/exclusions, denominator, cohort, sample size, or basis of comparison, such as `Growth accelerated after mid-April and ended at a period high` or `FY2021-FY2024, values in millions of USD`. Keep descriptions and subtitles hidden by default unless `showDescription` or an equivalent flag is needed to clarify the reading path.
-- Prefer human-readable dates in visible markdown, chart titles/subtitles, captions, table labels, and generated-date chrome. Keep ISO timestamps in query bindings, source metadata, and other machine-readable fields.
-- Do not use source table names, raw query ids, dashboard slugs, notebook paths, SQL intent, metric definitions, or implementation labels as chart/table subtitles. Put those details in source metadata, source notes, or supporting artifacts unless the source identity is itself essential for reader trust.
-- Before rendering report tables, check every table subtitle against the table title and visible columns. If it does not clarify what rows are in scope, what period is covered, how values are measured, which filters apply, or what comparison is being made, rewrite it or omit it rather than falling back to the source name.
-- Do not shrink visuals into unreadable sidecards. Use full-width blocks for dense charts, long labels, or HTML PNG images that need more room.
-- Put report charts on their own readable row or block in the reading flow unless a half-width layout has been checked in final context and remains legible. Do not use narrow right-rail chart cards for report evidence.
-- Report trend charts need enough observed data to make the shape worth reading. When a report chart would show only a few anchor periods, route back through `$visualize-data` to request a finer grain, longer lookback, or meaningful segment breakdown before rendering. If the source cannot support that without misleading the reader, replace the trend with a KPI strip, grouped period bars, table, or concise narrative comparison and record the omitted richer trend in source notes or supporting artifacts.
-- Report tables default to spacious density for low-row, narrative, presentation-ready tables. Use dense tables only for audit/detail tables or compact lookup data.
-- Reserve positive/negative table color for columns explicitly marked with `movement: true`, `semantic: "movement"`, or `role: "movement"`. Values in those columns should carry the intended sign or arrow, such as `+12%`, `-$4.2M`, `↑3 pp`, or `-18`. Keep composition, mix, share, percentile, and current-value columns neutral.
-- For multi-chart reports, keep a compact chart map in source notes or supporting artifacts. Name each visual's report segment, analytical question, selected family/type, fields, and supported claim. Repeated chart types need a reason; do not default every visual to a trend chart when report segments ask different questions such as status, mix, variance, drivers, or distribution.
-- When a report is exported or converted, every interactive or surface-native visual needs a readable static representation. Record a blocker if the static representation is missing or misleading.
-
-### Metrics And Language
-
-- Describe metrics in the user's language before exposing implementation details.
-- Clarify definitions, cohorts, denominators, filters, and comparison baselines before relying on a metric in the report.
-- Choose the most interpretable audience-facing grain: user, account, workspace, task, turn, session, request, revenue, endpoint, customer, org, or another business-facing unit.
-- Put raw numbers in context: percent of an active base, percent of the previous funnel step, percent of total change, comparison to baseline, target, peer segment, or historical range.
-- Use shorthand large numbers in narrative text, chart labels, and summaries, such as `899k`, `10.9k`, or `1.2M`. Reserve exact comma-separated values for audit tables, SQL outputs, appendices, or cases where precision changes the interpretation.
-- Keep implementation-facing event names, field names, table names, and exact predicates out of the main narrative unless they are essential for trust. Put them in caveats, source metadata, or short parentheticals.
-- Polish the final language for the selected audience: concise, answer-first, free of process notes, and no deeper on methodology than the audience needs to trust the result.
-
-## Quality Bar
-
-Before final handoff, confirm:
-
-- if any required item below fails, fix the report or record the blocking gap explicitly before finalizing
-- exactly one delivery mode and exactly one audience specification were used, unless the user explicitly asked for a hybrid or second delivery mode
-- the selected audience specification's `Required Structure` maps to visible report sections, with any merge, rename, reorder, or omission recorded in source notes or supporting artifacts
-- the report spine, report depth gate, selected delivery-mode specification, and rendered report were all checked
-- the rendered report answers the user directly, has visible reader-facing segment titles, and pairs each major claim with evidence, interpretation, caveats where needed, and a decision-useful implication
-- definitions, denominators, baselines, requested metrics, and caveats are clarified before final claims are treated as decision-ready; omitted metrics have a reason and needed follow-up
-- methodology depth fits the selected audience, and omitted requested metrics are explained with the reason and needed follow-up
-- visuals and tables were routed through `$visualize-data`, inspected in the selected surface, and remain readable with useful subtitles, adjacent explanatory paragraphs for every visualization, source metadata, and supporting notes
-- sources and reproducibility notes, chart maps, and omission reasons are preserved in metadata, source notes, or supporting artifacts without cluttering the visible report
-- the final handoff lists the selected report artifact plus relevant supporting evidence, not a chat-summary substitute or an unrequested parallel app plus HTML report

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

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Build Report"
-  short_description: "Turn reviewed evidence into polished analytical reports"
-  default_prompt: "Using this reviewed evidence, build a polished analytical report with clear narrative, charts, caveats, and source notes."
-policy:
-  allow_implicit_invocation: true

package/template/.codex/skills/data-analytics/skills/build-report/assets/executive-report-shell.html

@@ -1,70 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>{{TITLE}}</title>
-  <style>
-    body { font-family: ui-sans-serif, system-ui, sans-serif; margin: 0; background: #faf8f5; color: #171411; }
-    main { max-width: 880px; margin: 0 auto; padding: 40px 20px 64px; }
-    header, section { margin-bottom: 32px; }
-    h1, h2 { line-height: 1.15; margin: 0 0 12px; }
-    p, li { line-height: 1.6; }
-    figure { margin: 20px 0; }
-    figcaption { color: #5f5750; font-size: 14px; }
-    .callout { padding: 16px 18px; background: #f2ede6; border-radius: 12px; }
-    .executive-summary-box {
-      padding: 20px 22px;
-      background: linear-gradient(180deg, #f6f0e8 0%, #efe7dc 100%);
-      border: 1px solid #ddd1c2;
-      border-radius: 18px;
-      box-shadow: 0 12px 28px rgba(23, 20, 17, 0.06);
-    }
-    .executive-summary-box ul { margin: 0; padding-left: 22px; }
-    .executive-summary-box li + li { margin-top: 10px; }
-  </style>
-</head>
-<body>
-  <main data-report-audience="product stakeholders">
-    <header data-contract-section="title">
-      <h1>{{TITLE}}</h1>
-    </header>
-
-    <section class="executive-summary-box" data-contract-section="executive-summary">
-      <h2>Executive Summary</h2>
-      <ul>
-        <li><strong>{{Summary bullet 1}}</strong> [1]</li>
-        <li><strong>{{Summary bullet 2}}</strong> [2]</li>
-        <li><strong>{{Summary bullet 3}}</strong> [3]</li>
-      </ul>
-    </section>
-
-    <section data-contract-section="key-findings">
-      <h2>{{Insight-led findings heading}}</h2>
-      <p>{{Claim first, then evidence and interpretation}} [1]</p>
-      <figure>
-        {{Full-width chart or table}}
-        <figcaption>{{Short evidence note or caption}} [1]</figcaption>
-      </figure>
-    </section>
-
-    <section data-contract-section="recommended-next-steps">
-      <h2>Recommended Next Steps</h2>
-      <p>{{Actionable next step grounded in the findings}} [2]</p>
-    </section>
-
-    <section data-contract-section="further-questions">
-      <h2>Further Questions</h2>
-      <p>{{Important unresolved follow-up or narrowing question}} [3]</p>
-    </section>
-
-    <section data-contract-section="caveats-and-assumptions">
-      <h2>Caveats and Assumptions</h2>
-      <div class="callout">
-        <p>{{Only caveats that materially change interpretation}} [1]</p>
-      </div>
-    </section>
-
-  </main>
-</body>
-</html>

package/template/.codex/skills/data-analytics/skills/build-report/assets/technical-report-shell.html

@@ -1,66 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>{{TITLE}}</title>
-  <style>
-    body { font-family: ui-sans-serif, system-ui, sans-serif; margin: 0; background: #f8fafc; color: #0f172a; }
-    main { max-width: 920px; margin: 0 auto; padding: 40px 20px 64px; }
-    header, section { margin-bottom: 32px; }
-    h1, h2 { line-height: 1.15; margin: 0 0 12px; }
-    p, li { line-height: 1.65; }
-    pre { overflow-x: auto; background: #e2e8f0; padding: 14px; border-radius: 12px; }
-    figure { margin: 20px 0; }
-    figcaption { color: #475569; font-size: 14px; }
-  </style>
-</head>
-<body>
-  <main data-report-audience="technical">
-    <header data-contract-section="title">
-      <h1>{{TITLE}}</h1>
-    </header>
-
-    <section data-contract-section="technical-summary">
-      <h2>Technical Summary</h2>
-      <p>{{Main result directly, with the most important conditions}} [1]</p>
-    </section>
-
-    <section data-contract-section="key-findings">
-      <h2>{{Insight-led findings heading}}</h2>
-      <p>{{Claim first, then evidence and interpretation}} [1]</p>
-      <figure>
-        {{Full-width chart or table}}
-        <figcaption>{{Short evidence note or caption}} [1]</figcaption>
-      </figure>
-    </section>
-
-    <section data-contract-section="scope-data-and-metric-definitions">
-      <h2>Scope, Data, and Metric Definitions</h2>
-      <p>{{Scope, tables, definitions, filters, and grain}} [1]</p>
-    </section>
-
-    <section data-contract-section="methodology">
-      <h2>Methodology</h2>
-      <p>{{Method summary, validation approach, or modeling logic}} [2]</p>
-      <pre>{{Optional formula, pseudo-code, or query excerpt}}</pre>
-    </section>
-
-    <section data-contract-section="limitations-uncertainty-and-robustness-checks">
-      <h2>Limitations, Uncertainty, and Robustness Checks</h2>
-      <p>{{Known limitations and the checks that matter for trust}} [2]</p>
-    </section>
-
-    <section data-contract-section="recommended-next-steps">
-      <h2>Recommended Next Steps</h2>
-      <p>{{Actionable next step grounded in the results}} [3]</p>
-    </section>
-
-    <section data-contract-section="further-questions">
-      <h2>Further Questions</h2>
-      <p>{{Important unresolved follow-up question}} [3]</p>
-    </section>
-
-  </main>
-</body>
-</html>

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

@@ -1,108 +0,0 @@
----
-name: report-to-google-doc
-description: "Narrow conversion skill. Invoke only when the user explicitly asks to convert an existing local or blob-hosted HTML analytics report into a Google Doc, DOCX, or shareable document."
----
-
-# Report To Google Doc
-
-Use this skill when the user requests a local DOCX, a hosted DOCX, or a native Google Doc from an existing HTML analytics report. The source must be an HTML report: a local file, a downloaded blob-hosted report, or a report produced by `$build-report`
-HTML mode. This skill does not convert a live MCP app report directly.
-
-Choose the requested target: `local-docx` (default for local conversion), `hosted-docx`, or `native-google-docs`. HTML → DOCX is local work; uploading is a separate external action, performed only when requested. A hosted DOCX viewer is not a native Google Doc. Discover an available conversion/import capability and verify the result MIME/type before claiming native delivery.
-
-## 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 HTML report.
-
-   Use an absolute local path. If the user provides a remote report, retrieve it first and pass the local HTML file to the helper. If the file is a sign-in page, redirect page, or tiny stub, stop and obtain the real report.
-
-2. Run the bundled helper.
-
-   ```bash
-   python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
-     /absolute/path/to/report.html \
-     --out-dir /tmp/report_to_google_doc_plan
-   ```
-
-   The helper defaults to `--target local-docx`. Only for an explicit cloud request, select `--target hosted-docx` or `--target native-google-docs`; the helper still performs no remote action. If dependencies are unavailable and cannot be installed in the authorized scope, use an available local converter and validate against the source, or report the conversion gap.
-
-   Omit `--render-workers` on the normal path. Only pass a worker count after benchmarking the same report family locally. If dependencies are missing,
-   use a local virtual environment with `beautifulsoup4`, `pillow`, and `python-docx`; `cairosvg` or headless Playwright are optional renderers.
-
-3. Inspect helper outputs.
-
-   Required outputs:
-
-   - `skeleton.txt`: source text with stable placeholders
-   - `manifest.json`: parsed headings, tables, callouts, lists, styles, links,
-     and rendered visual inventory
-   - `preflight_checks.json`: source, width, DOCX, and rendered-image checks
-   - `report.docx`: generated local Word document
-   - `docx_upload_plan.json`: selected-target handoff plan (no upload steps for local conversion)
-   - `placeholder_queries.json`: source mapping debug labels
-
-   Do not upload until `preflight_checks.json` has `status: "passed"` with zero errors. Warnings must either be fixed or called out in the handoff.
-
-4. Complete the selected target.
-
-   For `local-docx`, validate the local DOCX against the source inventory and stop with its local link. Do not upload, change sharing, or require a Drive connector.
-
-   For explicitly requested `hosted-docx` or `native-google-docs`, discover the currently available upload/import capability and read its schema. Never guess a tool name, plugin ID or parameter. If missing, deliver the validated local DOCX and identify the cloud capability gap; do not claim cloud completion or switch the target silently.
-
-5. Verify and hand off.
-
-   Check headings, lists, tables, text, links and image relationships against `manifest.json`. For a cloud target, also reopen the returned document and verify content and actual native/hosted type. Return only the selected deliverable links plus source and validation evidence as useful. Connector success alone is insufficient.
-
-## Standards
-
-- Preserve every section, headline claim, metric card, metric definition,
-  source note, chart takeaway, recommendation, caveat, and link from the HTML report.
-- Preserve semantic formatting: headings, paragraphs, inline bold/emphasis,
-  inline code, positive/negative colors, links, lists, callouts, metric-card grids, tables, notes, captions, and charts.
-- Use DOCX-native structures wherever practical: headings, paragraphs, tables,
-  bullets/numbered lists, links, inline images, paragraph shading, table cell shading, and text styles.
-- Keep the report text column readable. Tables, charts, rendered table grids,
-  screenshots, and visual blocks must not exceed the DOCX page text width.
-- Preserve charts as inline PNG images from the source visual, aligned to the same left edge as text and tables. A chart with missing bars, missing legend swatches, or all-black/all-white marks fails validation even if the DOCX contains an image object.
-- Preserve multi-column report blocks. A two-column grid made only of titled mini-tables can remain a two-column rendered image capped to the text width;
-  mixed two-column blocks with narrative text, pills, callouts, or non-table panels should preserve that content natively instead of dropping it.
-- Do not expose customer-level details or sensitive links that were intentionally omitted from a sanitized report.
-- Do not write Google Docs batch-update artifacts such as `seed_requests.json`,
-  `remote_write_plan.json`, or `all_requests*.json`.
-
-## Repairs
-
-Use these fixes when validation exposes a conversion issue:
-
-| Problem | Fix |
-| --- | --- |
-| Heading is regular weight | Fix the DOCX writer heading style or explicit run bolding. |
-| Blank line after title or heading | Delete spacer paragraphs; skeletons should emit `\n`, not `\n\n`, after headings. |
-| Body paragraphs have too much space | Delete literal blank paragraphs and set modest style spacing. |
-| Table/image too wide | Set table columns or image width to the DOCX text column width. |
-| Chart has labels but missing bars | Inline SVG class styles or use a headless screenshot before inserting. |
-| Two-column table group is flattened | Treat the grid as one layout block with mini-table titles preserved. |
-| Executive summary, metric cards, or section is missing | Fix parser inventory before upload. |
-| Chart overlaps table | Insert the image on its own paragraph after the table. |
-| Chart duplicated | Remove the extra image; keep exactly one source-order copy. |
-| Inline bold/code/color missing | Fix manifest range splitting in the DOCX writer. |
-| Source links show raw URLs | Replace with native linked labels or native bullets using HTML link text. |
-
-## Local Checks
-
-```bash
-python3 -m py_compile <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py
-python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
-  /absolute/path/to/report.html \
-  --out-dir /tmp/report_to_google_doc_plan_smoke
-jq '.status, .summary' /tmp/report_to_google_doc_plan_smoke/preflight_checks.json
-test -f /tmp/report_to_google_doc_plan_smoke/report.docx
-test -f /tmp/report_to_google_doc_plan_smoke/docx_upload_plan.json
-git diff --check -- .codex/skills/data-analytics/skills/build-report/report-to-google-doc
-```

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

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Report To Google Doc"
-  short_description: "Convert existing HTML analytics reports into Google Doc or DOCX deliverables"
-  default_prompt: "Convert an existing HTML analytics report into a shareable Google Doc or DOCX deliverable."
-policy:
-  allow_implicit_invocation: false

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/scripts/report_to_google_doc/__init__.py

@@ -1 +0,0 @@
-"""Report-to-Google-Doc planning helpers."""

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/scripts/report_to_google_doc/cli.py

@@ -1,52 +0,0 @@
-"""Convert HTML to local DOCX and record the requested delivery target.
-
-No Google APIs are called. Local delivery is the default. Cloud planning requires
-an explicit target and never substitutes for capability discovery or authorization.
-"""
-
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-from .constants import DEFAULT_RENDER_WORKERS
-from .plan import write_outputs
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("html", type=Path, help="Local HTML report path")
-    parser.add_argument(
-        "--out-dir", type=Path, required=True, help="Directory for generated plan files"
-    )
-    parser.add_argument(
-        "--chart-mode",
-        choices=["image", "table"],
-        default="image",
-        help="Use rendered chart images by default; `table` writes simple parsed chart tables into the DOCX.",
-    )
-    parser.add_argument(
-        "--render-workers",
-        type=int,
-        default=DEFAULT_RENDER_WORKERS,
-        help=(
-            "Number of chart/table-grid images to render concurrently. "
-            "Default 0 auto-selects a conservative worker count; use an "
-            "explicit positive value only after benchmarking this report family."
-        ),
-    )
-    parser.add_argument(
-        "--no-strict-preflight",
-        action="store_true",
-        help="Write preflight_checks.json but do not fail the command when checks fail.",
-    )
-    parser.add_argument("--target", choices=["local-docx", "hosted-docx", "native-google-docs"], default="local-docx")
-    args = parser.parse_args()
-    write_outputs(
-        args.html,
-        args.out_dir,
-        chart_mode=args.chart_mode,
-        render_workers=args.render_workers,
-        strict_preflight=not args.no_strict_preflight,
-        target=args.target,
-    )