| name | evidence-synthesis |
| description | How to synthesize customer evidence from KG data into actionable narrative. Auto-invoked when producing evidence sections, selecting quotes, sizing problems, assessing impact, or writing insight summaries. Core rule: synthesize, never dump. Value is narrative, not retrieval.
|
| version | 5.0.0 |
Customer Evidence Synthesis
This skill governs how you turn raw KG query results into evidence that PMs, executives, and engineers can act on. The output should feel like analysis from a skilled researcher, not a database export.
Core Principle
Synthesize, never dump. The value you provide is narrative and interpretation, not raw retrieval. Anyone can pull numbers — what PMs need is someone to tell them what the numbers mean, why they matter now, and what to do about it.
Quote Selection Rules
CRITICAL: Use actual customer words, not AI summaries
Quotes MUST come from nli.content (the customer's verbatim words), NOT fi.content (the AI-generated summary). If a query returns fi.content, it is a summary — do not present it as a customer quote. Always query nli.content AS verbatim for customer-facing quotes.
CRITICAL: Every quote must have a date
Every quote MUST include its nli.record_timestamp as a date. A quote without a date has no temporal context — the reader can't tell if it's from yesterday or 2 weeks ago. Never omit the date.
How many: 3-5 maximum per section
More than 5 quotes becomes a data dump. Fewer than 3 feels cherry-picked. The sweet spot is 3-5 carefully chosen quotes that together tell a complete story. For top themes in reports, aim for 3+ quotes minimum.
Diversity requirements:
- Different subthemes — don't pick 3 quotes about the same narrow issue
- Different time periods — show the problem exists across time, not just one spike
- Different sentiment angles — if possible, include one that shows the severity (frustrated) and one that shows the impact (workaround, churn mention)
- Recency bias toward recent — lead with the most recent quote, but include at least one older quote to show persistence
Selection criteria (prefer quotes that):
- Illustrate with specific detail — "The CSV import fails every time I have more than 500 rows" > "Import doesn't work"
- Show business impact — "We had to manually re-enter 200 records" > "This is annoying"
- Represent the majority pattern — don't lead with an outlier
- Include context — quotes with timestamps, account info, or channel context are more credible
What to avoid:
- Generic one-word complaints ("Bad", "Broken")
- Quotes that require extensive explanation
- Multiple quotes making the same point
- Quotes with PII or sensitive information — redact if present
Citation format:
Every quote MUST include date AND a clickable "View in Enterpret" link. Use this exact format consistently:
> "{Quote text}"
> — {YYYY-MM-DD} · [View in Enterpret]({citationBaseUrl}{record_id})
Never use "View record" or just "View" — always "View in Enterpret".
Problem Sizing (Required)
Every evidence section MUST include these six dimensions:
-
Volume — how many feedback items mention this? Absolute number + proportion of total feedback if available.
-
Breadth — how many distinct accounts/users? One account filing 50 tickets is different from 50 accounts filing one each. If account data isn't available, say so.
-
Trend (WoW per theme) — direction + percentage for EACH theme, not just overall. "↑ 45% week-over-week" not just "increasing." Include the comparison periods. Every theme table should have a WoW trend column.
-
Recency — when was the most recent mention? "Most recent: 2026-03-06" tells the reader whether this is active right now or tapering off. Include this for each top theme.
-
Duration — is this new (appeared this week) or chronic (6+ months)? New + rising = escalate. Old + stable = systemic.
-
Channel mix + severity implication — where is this feedback coming from? Tickets only vs. tickets + reviews + social carries different severity.
Limitations Section (Required)
Every output MUST include a "What this evidence does NOT tell us" section. This is non-negotiable. Omitting limitations destroys trust with sophisticated PMs who know data has gaps.
Standard limitations to consider:
| Limitation | When to include |
|---|
| Sample size | Always if < 50 items. "N=23 — treat as directional." |
| Channel bias | Always. "This reflects [channels]. Users who don't contact support are invisible." |
| Segment gaps | When account data is unavailable or incomplete |
| Correlation ≠ causation | When suggesting impact or root cause |
| Survivorship bias | When relevant — "This only captures users who stayed long enough to complain." |
| Taxonomy coverage | When search returned few matches — the problem may exist under different labels |
| Recency bias | When most evidence is from the last few days of the window |
Be specific. "Data has limitations" is useless. "All 23 data points come from support tickets filed in the last 14 days — no app review or survey signal" is useful.
Output Calibration by Context
Different commands need different evidence density:
| Context | Evidence Depth | Quote Count | Limitations Depth |
|---|
Quick lookup (/find) | Concise summary — volume, sentiment, top quotes | 2-3 | One-line scope |
Deep analysis (/analyze) | Full block — this IS the deliverable | 3-5 | Full section |
Root cause (/analyze --rootcause) | Minimal — action-oriented | 1-2 most severe | Blast radius caveat |
Report — weekly/account (/report) | Their pain vs. market pattern or headlines | 2-3 | Completeness caveat |
Narrative Structure
When writing evidence narrative (not tables), follow this arc:
- Lead with the finding — what you discovered. Not how you discovered it.
- Size it — volume, trend, breadth.
- Interpret it — what does this mean for the product?
- Support it — quotes that prove the interpretation.
- Bound it — what we don't know.
Bad: "I queried the KG for themes matching 'checkout' and found 340 results with 78% negative sentiment across 3 subthemes..."
Good: "Checkout friction is the fastest-rising customer pain point this month — 340 reports, up 45% WoW, with 78% negative sentiment. It's concentrated in mobile web where users report the payment form resets on back-navigation..."
JTBD Signal Extraction
When customer feedback contains signals about underlying jobs, extract them in this format:
"When [situation], I want to [action], so I can [outcome]"
How to identify JTBD signals:
- Workflow descriptions — customers explaining what they're trying to accomplish
- Workaround mentions — reveals the job they're trying to get done despite the tool
- Comparison language — "In [other tool], I could..." reveals the job being hired for
- Goal statements — "I need to be able to..." or "We're trying to..."
- Success criteria — "It would be great if I could just..."
JTBD extraction rules:
- Extract no more than 2-3 JTBDs per evidence section — focus on the strongest signals
- Ground each in a specific quote — don't fabricate JTBDs from thin evidence
- Label inferred JTBDs as
HYPOTHESIS — "Inferred JTBD (HYPOTHESIS): When [X]..."
- Note how many customers expressed similar intent — a single customer's JTBD is an anecdote, 10 is a pattern
Insight Types
The KG categorizes feedback insights by type. Use this to interpret the nature of the signal:
| Type | What It Means | How to Use |
|---|
| COMPLAINT | Active frustration with current state | Strongest signal for prioritization |
| IMPROVEMENT | Suggestion for enhancement | Feature request signal |
| QUESTION | Confusion or lack of understanding | Documentation/UX clarity signal |
| PRAISE | Positive reinforcement | Protect/amplify what's working |
A theme that's 90% complaints is different from one that's 60% questions — the first needs a fix, the second needs better education.
