Research Template Synth

Overview

Turn a web research pass into a durable, reusable analysis / research report
template for any domain. The skill encodes the workflow we used to build the
user-analytics-toolkit report template: (1) breadth-first web retrieval,
(2) extract others' strengths into a borrow table, (3) author a
machine-fillable + human-readable report template with our own differentiators,
(4) optionally wire it into user-analytics-toolkit's report_engine so it is
generated from real data only, and (5) verify it actually renders from real
data with no fabrication.

The deliverable is a template that is not a blank document but a
decision-ready scaffold: every section carries a fill-in guide, maps to the data
source that feeds it, and ships with an anti-hallucination contract.

When to use

• User asks for a report/research/analysis template for a domain.
• User asks to "summarize best practices from articles/reports and form our own
  template".
• User wants to turn a literature/web research pass into a repeatable artifact.
• User already uses user-analytics-toolkit and wants its report output to
  follow a specific structure.

Workflow

Step 1 — Web research (breadth-first, multi-round)

Run 2–3 rounds of WebSearch. Do not stop at the first page of hits.

• Cover at least four source classes for the domain:
  1. Authoritative frameworks (e.g. NN/g, Google HEART, Jobs-to-be-Done).
  2. Tool-vendor templates (e.g. Maze, Dovetail, Koji, Usercall, Venngage).
  3. Practitioner / big-tech write-ups (e.g. Tencent, Alibaba research ops).
  4. Chinese-language practice (e.g. "用户研究报告 模板 结构 最佳实践").
• Use query_keyword_groups as an array of phrase strings (one phrase per
  group), NOT nested arrays. Example:
  query_keyword_groups: ["UX research report structure NN/g", "Google HEART metrics framework", "mixed methods research report deliverables"]
• In each round, read the result snippets and open 2–3 most-relevant pages with
  WebFetch to capture concrete structure (section lists, metric definitions).
• Keep a running list of source → concrete strength.

Step 2 — Synthesize "others' strengths"

Build a borrow table (source | what they do well | how we adopt it). Aim for
5–8 sources. Concrete strengths typically cluster around:

• Report as decision doc, not research log (Koji): every section serves a
  decision.
• BLUF + strict information hierarchy (Venngage / NN/g): execs decide from
  the exec summary alone.
• Finding ≠ theme ≠ recommendation, three layers separated (NN/g):
  observation = evidence, theme = interpretation, recommendation = action.
• Quant + qual triangulation under one metric vocabulary (Koji / Maze /
  Google HEART).
• Recommendations bound to KPI + expected impact (Usercall): ban vague
  "may help conversion".
• Report as living document + data lineage / guardrails (Maze / research
  ops).

See references/borrowed_best_practices.md for the seeded table we extracted
for the user-research domain — reuse it as a starting point and extend per
domain.

Step 3 — Build the report template

Author the template with three properties:

1. Decision-ready structure. BLUF exec summary first, then
   background → goals/scope → method & ethics → metrics dashboard →
   findings (observation/theme/recommendation split) → themes → quantified
   insights → opportunities & priorities → recommendation roadmap (KPI-bound)
   → risks/limitations → appendix → reuse tracker.
2. Machine-fillable + human-readable. Provide a {{field}} placeholder
   version (for user-analytics-toolkit report_engine) AND a plain Markdown
   version with inline fill-in prompts. Put example numbers only inside HTML
   comments so they never leak into the real report.
3. Our own differentiators (what "ours" adds beyond the borrow table):
   - Every section annotated with which function/module produces the data.
   - A fixed opportunity-scoring step (OST + Ulwick
   Importance + max(Importance − Satisfaction, 0)) to turn insight into a
   ranked priority list.
   - A mandatory ethics & lineage subsection (consent / IRB / data
   provenance) that most vendor templates omit.

Reference references/canonical_template.md for the 12-section skeleton
(including field placeholders, fill guides, and the borrow-to-section map).
Adapt section names/counts to the domain, but keep the decision-first spine.

Step 4 — (Optional) Integrate with user-analytics-toolkit

If the user has the toolkit and wants reports generated from real data:

1. Save the {{field}} template to
   user-analytics-toolkit/templates/<name>_report_template.md.
2. Generate via report_engine.template_report.generate_from_template(name, data, out_dir, ledger=..., strict=True). Pure data-fill by default = zero
   fabrication.
3. Enforce anti-hallucination with
   report_engine.antihallucination.enforce_no_fabrication(strict=True):
   - Missing fields render NO_DATA_SENTINEL, never invented.
   - Any LLM narration path is gated by number provenance; ungrounded numbers
   → quarantined, never published.
4. Reuse guardrails.CompletenessChecker as the publish gate.

See references/toolkit_integration.md for the exact wiring and a code snippet.

Step 5 — Verify the template renders from real data

Never hand over an untested template. Prove it works:

• Feed a real data dict (e.g. a user-analytics-toolkit pipeline run) into
  the generator. Confirm: status published, no leftover {{...}} or
  [...] placeholders, hallucination_issues == [].
• Negative test: feed a fabricated number (one not in the real data)
  through enforce_no_fabrication → expect ok=False / UNGROUNDED_NUMBER.
• Negative test: omit a field → expect the explicit sentinel, not a guessed
  value.

Anti-hallucination rules (critical)

These rules are non-negotiable and apply to Step 3–5 output:

1. No invented numbers. Every metric in the template/report must trace to a
   real artifact. If data is absent, render the sentinel
   ⚠ 无真实数据 —— 本报告未生成任何结论 and move on.
2. No placeholder leakage. A published report must contain zero {{field}}
   or [placeholder] tokens.
3. No speculative conclusions. Themes/recommendations must derive from
   stated findings; do not assert causal claims the data cannot support.
4. Separate layers. Keep observation (evidence), theme (interpretation),
   recommendation (action) distinct so a reader can audit the jump.
5. Cite sources in the borrow table. Borrowed structure is attributed; own
   additions are labeled "differentiator".

Resources

• references/borrowed_best_practices.md — seeded borrow table (user-research
  domain) to extend per project.
• references/canonical_template.md — 12-section template skeleton with field
  placeholders, fill guides, and borrow-to-section map.
• references/toolkit_integration.md — exact wiring into
  user-analytics-toolkit report_engine + anti-hallucination.
• scripts/build_template.py — deterministic helper that emits a Markdown
  report template from a domain name + section list (keeps field placeholders
  consistent).