Research To HTML

Research to HTML

Produce an evidence-led research artifact, not a source dump. It may explain a topic, compare mechanisms, test a claim, or support a decision. Keep evidence, reasoning, uncertainty, and presentation auditable from research through publication.

Load the contract

Read these references before acting:

1. research-protocol.md for scope, source quality, evidence ledgers, analysis, and privacy.
2. industry-report-writing.md for first-read independence, institutional report structure, analytical tone, and revision handling.
3. html-contract.md for deliverables, bilingual routing, visual hierarchy, accessibility, and validation.
4. master-prompt.md when translating a request into the reusable execution brief or when another agent needs the complete prompt.

Workflow

1. Define the research question or decision, audience role, scope, geography, operational terms, research cutoff, and exclusions. Ask only when an unresolved choice would materially change the result.
2. Inspect the target repository before creating files. Reuse its shared CSS, locale router, reading shell, report template, and validation script when present.
3. Browse current primary sources for unstable facts. Record direct URLs, source type, observed date, geography, caveat, and confidence.
4. Separate observation, inference, and unknowns. Test survivor bias, self-reported platform claims, stale examples, and metrics that do not establish the claimed business result.
5. Build the metric worksheet before synthesis when the question involves scale, change, frequency, profitability, prevalence, rankings, or comparisons. Preserve raw values, denominator, period, unit, formula, result, source, and caveat. Calculate shares, changes, ratios, ranges, or unit economics only when the inputs are comparable.
6. Write the Markdown evidence source before designing the report. Make every edition independently understandable to a first-time reader. Open with a short research-context block that states the background, the specific answer sought, and the main source groups. Keep claims, figures, formulas, limitations, and citations independently reviewable.
7. Compose separate English and Simplified-Chinese HTML pages from the same approved findings. Repeat the short research-context block near the top of each page, before the conclusion. Preserve numerical, causal, and uncertainty parity. Give each locale a self-canonical absolute URL and reciprocal absolute hreflang links.
8. Add only interactions that reduce understanding cost: reading depth, contents, theme, larger text, focused filtering, evidence calculators, historical timelines, and print support. Calculators may transform disclosed inputs but must not turn researcher judgment into a recommendation. A timeline belongs only when chronology is part of the evidence; it must not become a default action plan.
9. Update the repository catalog and concise bilingual project documentation when the report is publishable.
10. Run the repository validation gate, privacy scan, SEO metadata checks, JavaScript syntax checks, responsive and keyboard checks, both locales, print, deep links, and no-script fallback. Inspect the exact public artifact, not only the source tree.
11. Review the exact diff and publish only the intended files. Never force-push or stage unrelated workspace content.

Non-negotiable rules

• Do not infer profit from revenue, pledges, GMV, downloads, traffic, or funding success.
• Do not rank opportunities from incompatible denominators, overlapping collections, winner-only samples, or mixed periods. Show the mismatch or replace the ranking with a bounded hypothesis.
• Assign every quantitative claim a sample role before writing: population or complete frame, main observational sample, disclosure-only subgroup, or purposively selected illustrative cases. Keep these roles visibly distinct. Never use deliberately selected cases to calculate prevalence, coverage, success rates, population medians, or other x / y claims.
• Assign every taxonomy a role before publishing it: exhaustive mutually exclusive classification, overlapping multi-label grouping, or illustrative patterns. State that role in reader-facing language. Never let a case-led list or an early exploratory framework read like a complete classification of the main sample.
• When a disclosure-only subgroup would make a result look more prevalent than it is, prefer a conservative whole-sample lower bound: keep unknowns in the denominator and write “at least.” Otherwise name the subgroup in plain language. Never silently replace the report's main N with a smaller n.
• Every executive conclusion must point to a numeric observation, a directly cited qualitative observation, or an explicit Inference label. Do not leave naked top-line claims.
• For data-bearing questions, include at least three question-relevant raw measures, three reproducible derived measures, one counterexample, and one explicit data-completeness statement. If the source base cannot support this, say so and narrow the conclusion instead of filling the gap with general principles.
• Show numerator and denominator for percentages, name the comparison period, preserve units, and expose formulas in the report or evidence notebook.
• Prefer a finding-led paragraph: result first, number and comparison second, bounded interpretation third, limitation last. Avoid slogans, moral framing, metaphors, and generic business advice in evidence sections.
• Treat the headings in findings, analysis, comparison, and callout sections as the report's executive outline. Each one must state a reader-facing market, business, behavioral, economic, or technical result. Do not headline the researcher's workflow, proxy construction, parsing step, recalculation, or defensive caveat; keep those details in supporting prose or explicit method and limitations sections.
• Foreground subject-matter measures that answer the research question: businesses, people, revenue, profit, users, outcomes, or comparable units. Keep collection diagnostics—URL counts, request counts, pages parsed, row occurrences, parser or cache status, and field-coverage ratios—in the internal evidence notebook. Do not expose them in the hero, findings, evidence strips, comparison tables, or public source narrative unless the collection mechanism is itself the research subject or is indispensable to prevent a false conclusion.
• Write for an informed general reader in a plain professional register. Professional does not mean bureaucratic: prefer familiar words, natural sentences, and a clear reader benefit while keeping technical labels in the method and evidence layers.
• Define unfamiliar category names in everyday language and attach one or two evidence-backed examples when a label alone would not tell a general reader what the product does.
• Treat the subtitle as orientation, not a compressed abstract. In one natural sentence, tell readers what the report helps them understand; use at most one anchor number when useful, and move caveats to the nearby context or evidence-boundary block unless omitting one would make the subtitle misleading.
• Treat every published revision as a complete current edition. Do not assume the reader saw a previous version, conversation, sample, or methodology. Remove release-note language such as “previous version,” “original sample,” “expanded,” “now covers,” and “corrected parser,” together with their Chinese equivalents, unless temporal change is itself the research subject.
• When comparing a narrow and broad sample, define both in the current edition and frame the difference as a sensitivity, robustness, or coverage test. Do not narrate the collection history.
• Use “case review” or “案例核查” unless the evidence was subject to a real formal audit.
• Treat the reader as a reader, not as the presumed operator of a project. Never put a validation plan, project brief, implementation roadmap, action scorecard, recommended build sequence, or generic next steps inside the research report.
• When recommendations are explicitly requested, deliver them as a separate companion artifact, not as part of the report. Identify the evidence and value judgments behind them, and never present researcher preference as a measured result.
• Do not silently weaken caveats in the brief layer or in translation.
• Do not introduce unsupported numbers during HTML composition.
• Use a pie or donut chart only when categories are mutually exclusive, share one denominator, and cover the intended whole. Use bars for overlapping labels and show the denominator, overlap, and any unclassified remainder nearby.
• Cross-check every number written as a word or count in a title, heading, summary, caption, and callout against the actual rows or items beneath it in both locales. A heading that says three, eight, or another count must match exactly or clearly say that it is illustrative rather than exhaustive.
• Cite direct supporting pages, not search-result pages.
• Mark platform, vendor, or creator claims as self-reported when no independent audit exists.
• Keep real personal names, credentials, account identifiers, local paths, private URLs, and organization-specific secrets out of reusable prompts and skill resources.
• Preserve complete readable content without JavaScript.
• Keep English as x-default. Provide crawlable manual language links and persist explicit selection when useful; do not auto-redirect indexable pages from browser-language inference.
• Give every indexable page a unique title and description, absolute canonical and reciprocal hreflang, Open Graph and Twitter metadata, valid JSON-LD, favicon, internal trust links, and sitemap coverage.
• Publish Pages from an explicit reader-facing allowlist. Repository documentation, skills, scripts, templates, notebooks, hidden files, and local configuration must not enter the public artifact.
• Use a neutral organization-level byline unless a public author identity is intentionally required. Never leak local paths or private identity through content, metadata, Git history, or deployment artifacts.

Completion report

State the research cutoff, output paths, manual locale behavior, translated surface area, public artifact boundary, privacy and SEO validation commands, unresolved evidence gaps, and publication state.