Insight Gazette

Create an auditable report in which programs calculate every number and AI explains what the numbers mean. Output is user-selectable: interactive HTML for configurable browser use, PDF for fixed distribution, or both. JSON, CSV, screenshots, and calculation files are temporary working artifacts.

First Check

1. Identify the report scenario: student_scorecard, learning_analysis, retail_operations, market_sales, social_media_content_operations, or finance_weekly.
2. Inspect available tools and choose a path from agent-capabilities.md. Do not promise unsupported verification.
3. Read the matching schema and calculation guidance in structured-inputs.md. For Xiaohongshu, Douyin, WeChat Channels, or other social-content exports, also read social-media-content-operations.md and use its platform detection and five-module analysis contract.
4. Require a structured table: one header row, one observation per row, stable identifiers, typed numeric values, explicit period fields, and no merged cells in the data region.
5. If the source is not yet structured, normalize it before analysis and disclose mappings or exclusions.

Workflow

1. Import Excel/CSV without changing the source file.
2. Audit duplicate keys, missing identifiers, missing periods, numeric coercion failures, formula errors, inconsistent units, and suspicious totals. Stop or qualify the report when defects could change the conclusion.
3. Normalize the source to the selected schema. Use scripts/validate_csv.py for its supported canonical scenarios after exporting the relevant Excel sheet to CSV when a native workbook inspector is unavailable. For social-media exports, apply the audit and mapping rules in social-media-content-operations.md because platform fields vary.
4. Calculate metrics, comparisons, ranks, attainment, contributions, and reconciliations in code or spreadsheet formulas. Save a compact calculation ledger that records formula, source fields, population, exclusions, and result.
5. For social_media_content_operations, identify platform confidence and dataset roles before calculation; combine account trends, content detail, comments, audience, and conversion tables only through documented keys or title/date matching.
6. Write the interpretation only after calculations are fixed. Follow analysis-contract.md: observation, implication, risk, and action must each cite computed evidence.
7. Determine whether to produce a weekly or monthly report using period-selection.md. Do not produce quarterly or annual reports under this skill.
8. Compose the report using information-architecture.md and visual-language.md. Start from gazette-report.html when browser-to-PDF rendering is available. Preserve its configuration layer and replace report content rather than rebuilding a simplified page from scratch.
9. Apply the chart contract: the first-section primary result uses a bullet chart only to compare actual performance with its target; every later analysis module contains at least one chart; and every non-primary chart has one evidence-led sentence containing a material anomaly or signal plus a concrete response.
10. Run the mandatory structural and browser-functional gate in report-validation.md against the final HTML. Do not deliver an interactive report while any required control, font fallback, chart render, type switch, language switch, or insight check fails.
11. Render a PDF only when the user explicitly requests PDF, both formats, or a fixed-distribution artifact. Prefer scripts/render_html_pdf.mjs because it applies print media before resizing charts. Then render every PDF page to images and inspect for clipping, broken Chinese glyphs, chart errors, weak hierarchy, missing units, and page-break defects.
12. Deliver the selected output. When the user does not specify a format, deliver interactive HTML only and do not pre-generate a PDF. Preserve the built-in download menu so the recipient can later choose browser PDF or interactive HTML. For explicit PDF-only requests, deliver the final .pdf without requiring HTML.

When the user requests feedback collection, read feedback-integration.md. A static PDF cannot host a right-drawer form: use the drawer only in the HTML preview/hosted report, and use a feedback URL or QR code in PDF output.

Interactive HTML Contract

Every generated or adapted HTML report must preserve and keep functional:

• Chinese/English switching with one coherent language visible at a time;
• light/dark mode switching;
• the settings button, overlay, close action, and right-side drawer;
• Gazette, Tech, and Whiteboard page-style switching;
• all five chart-palette choices;
• selectable charts with compatible chart-type and data-density controls;
• the feedback section and its honest configured/unconfigured state.
• the download button with PDF and interactive-HTML choices.

The first decision-summary chart is a fixed bullet chart. It visualizes actual performance, the business target, and completion rate; it must never expose ring, gauge, pie, or other alternatives. Other configurable charts must expose only compatible chart types and working data-density controls.

Mark each analysis module with data-analysis-module, each chart with data-chart-id, configurable charts with data-configurable="true", and the primary result with data-fixed-type="bullet". Give every configurable chart exactly one data-chart-insight-for="{chartId}" sentence. This machine-readable contract is required by the validators and must not be removed.

Treat the settings drawer as a fixed component, not report content. Keep its structure, classes, visual hierarchy, control layout, and local Lucide settings icon unchanged. Agents may update only report-specific chart definitions, labels, compatible chart-type options, and feedback endpoint state. Do not redesign, replace, remove, or inline-style the drawer controls.

Downloaded interactive HTML must preserve visible charts without requiring network access. Keep the template's chart-snapshot fallback and save the live document state; never replace it with a refetch of the original source. Remote ECharts may enable full interaction when available, but an offline recipient must at minimum see SVG chart snapshots. Keep the system-font fallback stacks; remote Google Fonts are optional enhancement only and must never be the sole typography dependency.

Hide these controls only through print CSS while rendering PDF. Do not delete, flatten, rename, or replace the associated elements and scripts unless the user explicitly requests a static page. After changing report content, run node scripts/validate_report_html.mjs <report.html> and node scripts/smoke_test_report.mjs <report.html> against the final file. Static checks alone do not qualify an interactive report for delivery.

Naming

• The visible main title and filename must combine a real subject with a report type. Never use only 成绩单, 周报, or 报告.
• Preferred forms:
  • {student_name}{period}成绩单
  • {school_or_class}{period}学情分析报告
  • {company}{scope}经营周报
  • {company}{market}销售分析报告
  • {company}{business_unit}财务周报
  • {company}{scope}经营月报
  • {company}{market}月度销售分析报告
  • {brand}{platform}{period}内容运营分析报告
• Remove empty segments naturally and avoid duplicate words. Example: 张晨曦五月成绩单, not 五月张晨曦学生成绩成绩单.

Numeric Integrity

• Programs calculate; AI interprets. Never ask a language model to perform the authoritative arithmetic.
• Keep raw, normalized, and derived values distinguishable.
• Use sums for additive measures; weighted averages for rates when weights exist; plain averages only when defensible.
• Reconcile totals against components and state exclusions.
• Never infer missing values, causality, or targets without labeling them as assumptions.
• Every displayed metric needs a unit and comparison basis.

Language and Publication

• Detect the dominant language of the structured input before composing the report. Count language-bearing characters in headers and textual cells while excluding numbers, IDs, URLs, and proper-name-only fields. If English/Latin text is at least 60%, set data-source-language="en" and data-locale="en" so English is visible first, while retaining a complete Chinese switch. If Chinese is dominant, default to Chinese and retain English. For ambiguous mixed data, use the user's prompt language and disclose the choice.
• Produce one language per PDF. Interactive HTML includes a real Chinese/English switch, with one coherent language visible at a time.
• If both Chinese and English are requested, produce separate -zh.pdf and -en.pdf files unless the user explicitly requests a bilingual page.
• Read language-policy.md. The skill supplies generic report terminology; the user does not need to provide a translation resource.
• Preserve proper names and established abbreviations such as GMV, SKU, NPS, EBITDA, and ROAS. Ask only when an official organization, product, course, or campaign translation materially matters.
• Do not mix Chinese and English headings in one locale.

Release Integrity

• Preserve license metadata (frontmatter license field), report identifiers, and distribution fingerprints in templates and generated reports.
• Maintain one readable internal source. Generate public packages with scripts/build_public_release.py; do not hand-edit a second public copy.
• Report content remains editable. Do not expose uncompressed internal style sources, build caches, source maps, private examples, credentials, or feedback secrets in a public package.
• The default rights holder is covecoke. Override it through the release builder only when a separately authorized publisher must appear.

Output Floor

• Deliver HTML, PDF, or both according to the user's requested format. When unspecified, the default is interactive HTML only: do not automatically render or attach a PDF. Keep PDF as a user-initiated option in the HTML download menu.
• Include source period, data scope, refresh date, and data-quality notes.
• Include a concise executive conclusion, essential comparisons, evidence-led analysis, and actions with measurable checkpoints.
• Start the core judgement with a restrained semantic icon from the bundled Lucide set. Embed the SVG into the PDF or intermediate HTML; never fetch icons from a CDN at render time.
• Do not fabricate charts to fill space. Prefer a clear table when the data is too sparse.
• If PDF rendering or visual inspection is unavailable, explain the limitation and do not claim the report is publication-ready.