Research Reporter

Turns a synthesis file into something a stakeholder actually reads and acts on. Does not re-analyze anything — feedback-synthesizer already did the scoring, testing, and theming. This skill's job is presentation and prioritization for a specific audience, not new analysis.

---

Step 0: Who's reading this?

Ask (or infer from context if it's obvious) before drafting:

1. Audience: internal team/PM (fast, working doc) vs. leadership or external stakeholder (formal, polished). Run scripts/report_checks.py's select_format(audience) once you know which — "internal", "leadership", or "external" — rather than picking the format by feel.
2. Format: confirmed by the lookup above, or ask if the audience itself is genuinely unclear
3. What decision is this report supporting? Pull this from the original learning goal in 00-intake.md if it exists — the report should visibly answer that question, not just summarize everything that was measured

If there's no synthesis file to point to and someone asks for a report from scratch, stop and say synthesis needs to happen first — don't fabricate scores or themes to fill a report shape.

---

Step 1: Structure

Every report gets these sections, scaled by audience (internal = terse, formal = fuller prose):

Executive summary

2–4 sentences. Leads with the answer to the stated learning goal, not a recap of the method. State the headline score with its CI in plain language ("SUS came in at 74, meaningfully above our 68 benchmark — not just noise, the confidence interval doesn't overlap").

Keep three things distinct and never let one stand in for another: statistical significance (did synthesizer's test actually return significant?), practical significance (does the size of the difference matter for the decision this study was run for — a statistically significant 2-point movement on a huge sample may not be worth acting on; say so when it applies), and evidence confidence (how much to trust the conclusion overall, carried forward from synthesis — see Step 3). A narrow CI is not evidence of high confidence; a significant result is not automatically an important one.

Methodology

Instrument used, n, collection window, and the low-confidence flag if feedback-synthesizer raised one — carry that flag forward, never drop it during formatting. Keep this section short for internal docs, fuller for formal ones (formal audiences need to trust the number before acting on it).

Benchmark comparison

Pull the product's history from /research/_benchmarks/<product>.md and show the trend, not just this wave's number in isolation — but only once research-loop's check_benchmark_comparability (or feedback-synthesizer, if it already ran this check) confirms the waves being compared actually measured the same thing. When it reports a mismatch, present the waves side by side with the mismatched fields named, instead of a trend line that implies more comparability than the measurement conditions support. A single score with no trend line is a weak report; a trend line built on an apples-to-oranges comparison is a misleading one.

Findings

Present the synthesis's qual-quant cross-references as-is — don't soften a stated "no clear theme explains this" into a manufactured narrative. If synthesis said a movement was unexplained, report it as unexplained.

Prioritized recommendations

Derived directly from feedback-synthesizer's severity tiers (Critical / Notable / Minor) — this skill doesn't re-rank them, it translates tiers into recommended actions and rough effort/impact framing for the stakeholder. Critical tier findings go first, always.

---

Step 2: Audience-specific formatting

Internal / markdown / Notion:

• Terse, scannable, bullet-heavy
• Assume the reader already has product context — skip background explanation of what the product is
• Fine to reference raw synthesis file for anyone who wants to dig in

Formal / docx:

• Fuller prose, more framing/context for readers without daily product exposure
• Route section copy (headers, section framing, any narrative transitions) through thought-leadership-writer if the doc is going to leadership or an external audience and needs a stronger narrative voice; route any UI-facing copy referenced in findings through righter for consistency with product copy standards
• Use the docx skill for actual file generation and formatting

---

Step 3: What never changes between formats

Regardless of audience, these must survive unchanged from the synthesis file:

• The headline score and its confidence interval
• Whether a difference was statistically significant
• The low-confidence flag, if one was raised
• Severity tier assignments, including a stated override reason when override_reason is set — never present just the final "Critical" label as if the frequency math alone produced it
• Evidence confidence (the categorical rating, not a re-derived number)
• Each finding's claim-strength level — never let "correlated" read as "caused" in the prose, even when the report's tone is more confident than the synthesis's
• Any "no clear theme found" / "cannot determine" statements

Reformatting for readability is fine. Softening a caveat, dropping a CI because it "clutters" the exec summary, upgrading "directional" to "confirmed," or upgrading a claim-strength level, is not.

Before finalizing, run these checks from scripts/report_checks.py: validate_report_structure(report_text) to confirm all five required sections are present; check_preserved_values(synthesis, report_text) to confirm the CI, low-confidence flag, severity tiers, evidence confidence, and claim-strength labels survived into the text unchanged; check_no_unsupported_causal_language(synthesis, report_text) to catch causal-sounding verbs ("caused," "led to," "drove") appearing without a theme that actually carries claim_strength="causal". All three are structural/textual checks — they catch a dropped number, a missing section, or an unsupported causal verb, but they cannot catch a report that keeps every number yet quietly reframes "directional" as "confirmed" in prose, or "correlated" as "clearly caused by" without using the word "caused." That specific failure mode needs an actual read-through; don't treat a clean script pass as proof the report is honest, only as proof it isn't missing pieces or an obviously upgraded verb.

Write /research/<study-name>/03-report.json alongside the .md/ .docx — run validate_report_json(report) first and fill in anything it reports missing. The .json is canonical, same convention as every other artifact in this system.

---

Rules

Priority when rules interact: STOP > MUST NOT > MUST > SHOULD > MAY — see ux-research/README.md for the full precedence explanation.

• STOP if there's no synthesis file to point to and someone asks for a report from scratch — say synthesis needs to happen first, don't fabricate scores or themes to fill a report shape.
• MUST NOT re-score, re-test, or re-theme anything — that's synthesizer's job.
• MUST NOT drop a confidence interval, low-confidence flag, evidence confidence rating, or claim-strength label to make the report cleaner.
• MUST NOT upgrade a claim-strength level in prose (e.g. "correlated" read as "caused") — check_no_unsupported_causal_language is the enforcement point; don't work around it by rewording instead of fixing the substance.
• MUST NOT re-order severity tiers based on its own judgment, or present an overridden tier without its override reason.
• MUST NOT present a benchmark trend when the waves aren't comparable — present them side by side instead.
• MUST NOT write UI or public-facing copy without routing through righter or thought-leadership-writer as appropriate.
• MUST NOT manufacture a narrative explanation for a score movement synthesis explicitly said was unexplained.
• MUST present a benchmark trend, not just this wave's score in isolation, when comparable prior waves exist.

---

Quick reference

Audience	Format	Tone
Internal team / PM	Markdown / Notion	Terse, bullet-heavy, assumes context
Leadership / external	Word doc (docx)	Fuller prose, more framing
Report going external/public	Docx + thought-leadership-writer pass	Narrative voice
Findings reference UI copy	Route through righter	Copy standard consistency
No synthesis file exists	Stop, redirect to feedback-synthesizer	—