Research

Scope: How we plan and execute product-grounded research for quickstart dashboard packs—not only what to mine from a repo, but how to build a durable library of examples, personas, and questions, and which foreign disciplines we borrow from.

Executable per-connector checklist remains in .codex/skills/quickstart-product-dashboard-research/SKILL.md. This doc is the program-level companion: meta-methodology, evidence strategy, and thinking frameworks.

Why this initiative exists

Quickstart dbt projects are shaped by source APIs and typical reporting. Analysts already have mental models from the vendor UI and from how their teams talk about work (pipeline reviews, ticket queues, QBRs). Dataface packs should meet them there while staying honest about what the modeled tables can answer.

We are not competing with the vendor’s pixel-perfect UI—we are encoding question types, navigation habits, and cadence (daily vs quarterly) into YAML backed by the quickstart star schema.

Part 1 — Meta: how to plan the research (before you open the vendor app)

Research on research: treat each connector as a mini product-discovery cycle with explicit phases so outputs are comparable across Salesforce, Zendesk, HubSpot, etc.

1.1 Charter (one page per connector)

Before deep diving, write:

This prevents endless “one more dashboard” creep and aligns gaps with scope cuts, not “silent failure” in YAML.

1.2 Phased workflow

Charter → Inventory sources → Extract examples → Personas & questions → Map to model → Topology & links → Gap log → Retro

Adjust per connector complexity; write down actuals in the connector retro for program improvement.

1.3 Artefact standards (so the library stays useful)

Every connector folder should include:

• research.md — narrative + synthesis (this structure).
• sources.md — bibliography: URLs, doc sections, “last verified” date, access notes (public vs trial).
• examples/ — indexed list: “Example ID, name, source URL, object/metric focus, persona, cadence, screenshot optional.”
• questions.md or section in research.md — question bank (see Part 4).
• link-matrix.md — board-to-board navigation intent (even before dashboard linking ships).
• gaps.md — product vs quickstart; feeds modeling or explicit “not in v1.”

Naming: ai_notes/quickstart-dashboards/<connector-slug>/ or a dedicated workspace repo—pick one convention in program setup and do not fork per author.

Copy-paste templates: ai_notes/quickstart-dashboards/_templates/ (charter, research, sources, examples/index, questions, link-matrix, gaps).

1.4 Quality bar for “done enough”

Research is done when:

1. Another builder can implement YAML without re-opening vendor tabs for basics.
2. Every default-ish dashboard type you claim parity with has either a model anchor or a gap entry.
3. Personas have at least three cadences represented (see Part 4): operational, rhythm-of-business, planning.
4. Sources are dated; known stale sections are flagged.

Part 2 — Disciplines and “skills” to steal from

We are doing hybrid product research + analytics design + competitive intel. Explicitly borrow methods and language from:

2.1 Jobs-to-be-done (JTBD) and outcome chains

• Job story framing: “When I [situation], I want to [motivation], so I can [outcome].”
• Outcome chain: raw event → roll-up → comparison → decision → action (e.g. ticket reopened → team backlog → SLA breach → escalation).
• Steal for: turning “cool chart” lists into why this exists—feeds board titles, section order, and link targets.

2.2 UX / service design / journey maps

• Swimlanes by role (agent vs lead vs exec).
• Touchpoints: where they live in-product (home, list view, record, admin analytics).
• Steal for: board topology (overview vs entity detail vs admin), and where deep links must land.

2.3 Sales engineering and “first demo” narratives

• Vendors and partners structure demo stories (quarterly business review, Monday morning pipeline, support standup).
• Steal for: canonical question scripts—“If you only had five minutes with a RevOps lead, which five cuts of data?”

2.4 Competitive and ecosystem intelligence

• Adjacent BI templates: Salesforce dashboards in Tableau/Looker galleries (as pattern references, not asset copies), industry “starter” workbooks, partner solution guides.
• Embedded analytics: Many SaaS products embed standard explores (Looker, Omni, etc.); screenshots and “metric definitions” pages describe intended semantics.
• Steal for: naming consistency and metric families (pipeline, backlog, aging, conversion) that recur across tools.

2.5 Technical writing and information architecture

• Docs hierarchies: “Objects → fields → reports that use them.”
• Steal for: mapping vendor object model to quickstart facts without inventing joins the model doesn’t support.

2.6 Analyst ethnography (lightweight)

• Reddit, Stack Exchange, vendor forums, “how do I report on X” threads—phrasing of real questions.
• Steal for: natural-language question bank and agent-eval prompts later (aligns with M2 catalog/planning work).

2.7 Evaluation / rubric thinking (from our own eval initiatives)

• Treat question coverage like a rubric: persona × cadence × chart type × entity depth.
• Steal for: pilot sign-off—“we scored green on operator daily, yellow on exec quarterly until gap G-12 is modeled.”

Part 3 — Building the example and evidence library

3.1 What counts as an “example”

An example is anything that constrains pack design:

Each row in examples/ index should tag: source tier (P0 = native product, P1 = official doc, P2 = community/pattern).

3.2 Capture policy

• Prefer links + quotes over screenshots; screenshots rot and can blur fair-use boundaries—use for internal research only unless license-clear.
• Always record: capture date, URL, product area name, what question the example answers (one line).
• Never treat a third-party workbook as “canonical semantics” without vendor doc cross-check when the metric is legally/commercially sensitive (revenue, pipeline).

3.3 Anti-patterns

• Screenshot hoarding without question mapping—junk drawer, not a library.
• Parity theater—listing 40 dashboards when v1 ships 4 boards; use coverage matrix instead: example → planned board or gap.
• Undated sources—six months later nobody knows if the UI moved.

3.4 Consolidation across connectors

At program level (not only per slug):

• Pattern cards: reusable motifs—“ticket aging histogram,” “pipeline by stage snapshot,” “account 360 header KPI strip.”
• Cross-product glossary: same job (“deflection”) may differ per vendor—note terminology drift.

Store pattern cards under e.g. ai_notes/quickstart-dashboards/_patterns/ or initiative-maintained folder—TBD in program setup.

Part 4 — People, activities, and questions (deep framing)

4.1 Who are the people?

For each connector, maintain an explicit persona table (minimal v1: 3–5 rows):

Add partner / finance / product only when the quickstart model actually supports those cuts.

4.2 What do they do with the product? (activities)

Bucket activities (verbs), not org-chart titles:

• Triage — sort, prioritize, assign.
• Execute — log work, communicate, resolve.
• Review — standup, pipeline review, QBR prep.
• Plan — capacity, targets, territory, roadmap.
• Govern — access, data quality, audit.

Map each activity to question clusters (see 4.4).

4.3 Cadence: day-to-day vs rhythm-of-business vs planning

Questions and dashboard granularity change by horizon:

A strong pack has at least one plausible board or section per cadence or a documented gap (“QBR-style cohort analysis not in quickstart—use warehouse”).

4.4 Question bank structure

For each connector, maintain 30–80 questions over time (v1 might ship 10–20 satisfied, rest backlog/gap).

Per question row:

• Id (stable: ZD-OPS-014)
• Natural language (how a human asks)
• Persona
• Cadence (operational / tactical / strategic)
• Activity (triage, review, …)
• Visualization type (overview, ranking, trend, funnel, entity detail)
• Primary entity (ticket, account, user, …)
• Model anchor (table.column or “GAP”)
• Risk (optional: text-to-SQL ambiguity, many-to-many)

Group questions into episodes—narratives that span boards (“Monday morning support lead”: queue depth → agent load → escalation list).

4.5 From questions to boards (design heuristic)

• High frequency + shared → overview board.
• Deep entity semantics → detail board with stable key in URL (once dashboard linking is ready).
• Rare but political (exec) → small snapshot section or explicit out of scope with reason.

Part 5 — Signals to mine (per repo) — expanded

Already familiar; expand with program discipline:

• dbt: README, schema.yml, exposures, analyses/, semantic/metrics layers, tests naming (often reveal grain).
• Vendor docs: report catalogs, analytics modules, object reference, “understanding” guides, release notes (metrics renames!).
• API shapes (indirect): sometimes explain why quickstart has strange keys—helps agent and author mental models.
• Community: Stack Overflow patterns, r/salesforce, vendor forums—for phrasing and rank-ordered pain.
• Third-party BI: search “<Product> dashboard template” for layout patterns—verify semantics in vendor docs.

Part 6 — Hypotheses to test in pilots

1. A small board set (3–5 YAML files) with strong linking beats many flat boards for recognition and adoption.
2. Research notes that include a link matrix and question IDs reduce rework when adding a third connector.
3. Gaps between vendor questions and quickstart facts cluster by connector family (CRM vs support vs billing)—useful for prioritizing modeling vs scope cuts.
4. Cadence tagging predicts which boards analysts open first—validate with pilot feedback or lightweight telemetry later.
5. A shared _patterns/ library pays off after three connectors by speeding board naming and YAML structure.

Part 7 — Program-level research roadmap (meta timeline)

References

• Initiative tasks (pilots): see index.
• Executable checklist: .codex/skills/quickstart-product-dashboard-research/SKILL.md.
• Board linking (blocking rich navigation in packs): Dashboard linking initiative, dashboard-linking-v1 task, landscape research.
• URL variables (Cloud): ai_notes/considerations/INTERACTIVE_VARIABLES_HTML.md.

Changelog

• 2025-03-20: Expanded with meta-methodology, disciplines to borrow, evidence library standards, personas/cadences/question bank, program roadmap.