> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase27-session10-demand-centers/spec.md). # Session Specification **Session ID**: `phase27-session10-demand-centers` **Phase**: 27 - Trend Finder Alpha Radar Adoption **Status**: Not Started **Created**: 2026-06-13 *** ## 1. Session Overview This session adds Demand Centers to Trend Finder by extracting question-shaped evidence from already-collected discussion-role sources, clustering similar questions across topics, and rendering a bounded creator brief panel in the Brief surface. It ports the useful Alpha Radar demand cluster concept without copying Alpha Radar's inferred counts or unlabeled estimates. The implementation stays script-only for extraction and analysis. It uses existing evidence, topics, daily history, analyst runtime, and schema validation paths, then exposes only browser-safe demand clusters through the validated Trend Finder payload. No new public source adapters, source calls, or Google Trends behavior changes are introduced. Demand Centers should help a creator answer "what are people asking for?" from the evidence already collected. Every published number must be either an observed question-evidence count or explicitly labeled as derived from existing history. Missing, low-sample, fallback, and empty states must be visible instead of implying invented demand. *** ## 2. Objectives 1. Extract question-shaped discussion evidence deterministically from existing source items. 2. Cluster similar questions into bounded demand centers linked to related canonical topic IDs and cited evidence IDs. 3. Add analyst-written cluster briefs with deterministic fallback text and strict validator checks. 4. Render Demand Centers in the dashboard Brief and static Brief paths with explicit count labels, provenance, empty states, and topic jump-links. *** ## 3. Prerequisites ### Required Sessions * [x] `phase27-session01-brief-movement-groups-and-calibration-metrics` - Brief layout, movement grouping, and calibration panel patterns are available. * [x] `phase27-session04-daily-time-series-persistence-and-sparklines` - Private daily history exists for optional observed week-over-week growth derivation. ### Required Tools/Knowledge * Bun 1.3.14, TypeScript, Vitest, and existing Trend Finder focused test suites. * Zod additive defaults in `src/extensions/trend-finder/schema.ts`. * Analyst prompt, validation, repair, and fallback patterns in `scripts/lib/ai-runtime/trend-analyst.ts`. * Spend-accounting label discipline from `scripts/extensions/trend-finder/spend-accounting.ts`. * Static Brief projection and rendering boundaries in `scripts/extensions/trend-finder/static-brief-export.ts` and `scripts/extensions/trend-finder/static-brief-renderer.ts`. ### Environment Requirements * No AI runtime credentials are required; deterministic fallback must produce useful clusters without external services. * No source credentials or new source calls are required; the feature consumes already-collected evidence only. * Generated private Trend Finder snapshots and cache artifacts stay out of git. *** ## 4. Scope ### In Scope (MVP) * Trend Finder can identify question-shaped discussion evidence - Extract from existing evidence titles and snippets using question marks and question-word openings. * Trend Finder can cluster cross-topic demand - Normalize question text, group similar demand shapes with deterministic token-overlap heuristics, bound cluster count, and preserve stable ordering. * Trend Finder can publish observed demand counts - Expose real question-evidence counts only, plus optional derived growth context when daily history supports a week-over-week comparison. * Trend Finder can link demand back to topics - Store bounded `relatedTopicIds` and cited evidence IDs validated against current topics and evidence. * Trend Finder can write creator-facing demand briefs - Allow analyst text when valid and fall back deterministically when AI is unavailable or invalid. * Operators can inspect Demand Centers in Brief - Render cluster cards with count labels, provenance, related topic jump-links, and explicit empty states. * Focused tests cover extraction heuristics, clustering bounds, count integrity, validator rejection, fallback briefs, UI projection, and static Brief privacy boundaries. ### Out of Scope (Deferred) * Invented asker counts or open-window day estimates - *Reason: Alpha Radar's values are inferred and conflict with Trend Finder's no-invented-metrics rule.* * New sources or new source calls - *Reason: source expansion requires a compliance-first phase and source-specific review.* * Google Trends demand scope changes - *Reason: the existing optional Google Trends path remains metric-only and opt-in.* * Embedding-based clustering - *Reason: dependency and model decisions belong to Session 11's investigate-only spike.* * Persisting demand clusters as a separate store - *Reason: MVP demand centers are derived during the existing collector run and bounded in the generated payload.* *** ## 5. Technical Approach ### Architecture Add a script-side `demand-clusters` helper that accepts current evidence, topics, and optional historical topic context. It filters to discussion-role evidence, extracts normalized question shapes from titles and snippets, groups similar questions by deterministic token overlap, and emits bounded cluster candidates with observed evidence counts, cited evidence IDs, and related topic IDs derived from topic evidence overlap. Extend the Trend Finder schema with a top-level `demandClusters` branch using Zod defaults so legacy payloads keep parsing. Each cluster includes a stable ID, question shape, creator brief, evidence count label, count provenance, optional derived growth context, related topic IDs, cited evidence IDs, and analysis provenance. Validators and collector checks reject clusters that cite unknown evidence IDs or topics. The analyst path may improve the `creatorBrief` for cluster candidates, but it must not invent counts, dates, sources, URLs, or related topics. If the runtime is disabled or output fails validation, deterministic fallback builds briefs from the question shape, related topic names, and creator lens context. Browser UI and static Brief rendering consume only the validated schema branch through view-model projection. ### Design Patterns * Additive schema defaults: Legacy generated payloads parse with `demandClusters: []`. * Script-only runtime boundary: Extraction, clustering, growth derivation, and fallback text stay under `scripts/`. * Explicit provenance labels: Counts are `observed`; growth is `derived` or unavailable. * Project before rendering: Dashboard and static Brief surfaces render view-model or projection rows, not raw collector intermediates. * Deterministic ordering: Clusters sort by observed count, related topic priority, and stable ID tie-breakers. * Bounded payloads: Cluster count, evidence citations, topic links, and text lengths are capped. ### Technology Stack * TypeScript with existing project path aliases and strict local contracts. * Zod for runtime schema validation and browser-safe defaults. * React 19 and Tailwind CSS 4 for the Brief panel. * Bun and Vitest for focused script, schema, collector, view-model, and static Brief tests. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------- | | `scripts/extensions/trend-finder/demand-clusters.ts` | Extract, normalize, cluster, bound, and label question-shaped discussion evidence. | \~240 | | `scripts/extensions/trend-finder/__tests__/demand-clusters.test.ts` | Focused tests for extraction heuristics, clustering bounds, counts, topic links, growth labels, and fallback briefs. | \~240 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------- | | `src/extensions/trend-finder/schema.ts` | Add demand cluster schema, constants, types, defaults, and legacy parse behavior. | \~130 | | `scripts/lib/ai-runtime/trend-analyst.ts` | Extend analyst request/output validation for optional demand cluster briefs without allowing invented references. | \~140 | | `scripts/extensions/trend-finder/collector.ts` | Build demand clusters from current evidence/topics/history, merge analyst/fallback briefs, and publish bounded payload fields. | \~140 | | `src/extensions/trend-finder/view-model.ts` | Project demand clusters into display labels, provenance tones, related topic labels, and evidence links. | \~110 | | `src/extensions/trend-finder/views/brief-view.tsx` | Render Demand Centers panel with empty states, count/provenance labels, and related topic jump-links. | \~120 | | `src/extensions/trend-finder/views/trends-view.tsx` | Support demand topic jump-links by selecting hash-targeted related topics on entry. | \~50 | | `scripts/extensions/trend-finder/static-brief-export.ts` | Project demand clusters into static Brief rows through sanitized output boundaries. | \~80 | | `scripts/extensions/trend-finder/static-brief-renderer.ts` | Render static Demand Centers section with escaped text and labeled counts. | \~80 | | `src/extensions/trend-finder/fixtures.ts` | Add bounded fixture coverage for demand cluster UI and legacy default behavior. | \~50 | | `src/lib/__tests__/trend-finder-schema.test.ts` | Add schema default, bounds, and invalid reference coverage for demand clusters. | \~90 | | `scripts/lib/ai-runtime/__tests__/trend-analyst.test.ts` | Add demand brief validation, invented-reference rejection, and fallback acceptance tests. | \~110 | | `scripts/extensions/trend-finder/__tests__/collector.test.ts` | Add collector integration tests for demand cluster publication and no-new-source behavior. | \~120 | | `src/extensions/trend-finder/__tests__/view-model.test.ts` | Add demand cluster projection tests for labels, ordering, and topic/evidence links. | \~90 | | `src/lib/__tests__/trend-finder-dashboard.test.tsx` | Add Brief Demand Centers rendering, empty state, and jump-link coverage. | \~90 | | `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts` | Add static projection and privacy-safe demand row tests. | \~80 | | `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Add static HTML rendering tests for demand labels and escaping. | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Demand clusters are generated only from already-collected discussion-role evidence. * [ ] Every cluster cites known evidence IDs and related topic IDs, with unknown references rejected or dropped before browser publication. * [ ] Every published count is an observed question-evidence count or carries an explicit `derived` unavailable/growth label. * [ ] Deterministic fallback produces useful cluster briefs without live AI. * [ ] Brief Demand Centers cards link back to related topics in the Trends view. * [ ] Legacy payloads without `demandClusters` keep parsing. ### Testing Requirements * [ ] Unit tests cover question extraction, clustering, count integrity, bounds, ordering, and fallback briefs. * [ ] Schema and analyst tests cover invalid references, invented metrics, and legacy parse defaults. * [ ] Collector tests prove no new source call is introduced. * [ ] UI and static Brief tests cover demand rendering, empty states, escaped text, and topic jump-links. ### Non-Functional Requirements * [ ] Browser-visible payload remains bounded under the shared 1 MB extension payload limit. * [ ] Raw prompts, provider responses, logs, Actor inputs, tokens, private paths, and raw source payloads do not enter browser state or static export. * [ ] Source compliance posture remains unchanged because no new collection path is added. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Focused Vitest suites for changed files pass. * [ ] `bun run typecheck:scripts` and relevant app type/schema tests pass. *** ## 8. Implementation Notes ### Key Considerations * Keep "demand" as observed discussion evidence, not a market-size estimate. * Derive related topics only from current topic/evidence relationships. * Cap cluster count and citations before any browser schema boundary. * Preserve deterministic fallback quality because live AI may be disabled. * Use clear labels: observed count, derived growth, fallback brief, and no demand detected. ### Potential Challenges * Question extraction false positives: Mitigate with question-word openings, question mark checks, minimum token count, and discussion-role filtering. * Cross-topic duplicate clusters: Mitigate with normalized token overlap, stable merge rules, and deterministic sorting. * Analyst prompt creep: Mitigate by sending bounded cluster candidates and accepting only brief text for known cluster IDs. * Jump-link drift between Brief and Trends: Mitigate by testing hash-targeted topic selection and stable topic IDs. * Payload growth: Mitigate with hard caps on cluster count, citations, related topics, and text lengths. ### Relevant Considerations * \[P02] **Extension payloads and demo labels stay bounded**: Demand cluster arrays, citations, labels, and fallback states must stay capped and explicit. * \[P02] **New source adapters need per-source compliance review**: This session adds no adapters and consumes already-collected evidence only. * \[P15] **Aggregate collection must stay budgeted**: Analyst demand briefs must degrade to deterministic fallback instead of stalling collection. * \[P24] **Browser-safe export and triage boundaries**: Static Brief receives sanitized demand rows only, not raw evidence payloads or private state. * \[P24] **Additive defaults keep legacy payloads alive**: New schema fields must default safely for old fixtures and generated payloads. * \[P24] **Project before rendering**: Static and dashboard Brief rendering should consume projected demand rows, not raw collector intermediates. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Demand counts may be mistaken for unique people or market size unless labels make observed evidence count explicit. * Invalid analyst output could invent cluster references unless validation is closest to the analysis boundary. * Brief jump-links could leave users in the wrong context unless the Trends view revalidates selected topic IDs on entry. *** ## 9. Testing Strategy ### Unit Tests * Test question extraction from titles and snippets, including non-question discussion evidence that should be ignored. * Test cluster merge bounds, deterministic ordering, evidence count integrity, and related topic derivation. * Test schema defaults, text caps, reference validation, and legacy payload parsing. * Test analyst demand brief validation and deterministic fallback output. ### Integration Tests * Test collector publication from fixture evidence through parsed Trend Finder payload. * Test static Brief projection and renderer escaping for demand clusters. * Test view-model projection for labels, tones, topic links, and evidence links. ### Manual Testing * Run a fixture-backed Trend Finder payload and open the Brief tab. * Confirm Demand Centers appears when discussion questions exist and shows an empty state when none exist. * Follow a related topic link from Brief to Trends and confirm the expected topic is selected. * Confirm generated static Brief output contains demand labels without private paths or raw source payloads. ### Edge Cases * No discussion-role evidence. * Discussion evidence without question-shaped text. * Multiple questions mapping to the same related topics. * Analyst output for unknown cluster IDs, evidence IDs, topic IDs, or invented metrics. * Historical context unavailable for growth comparison. *** ## 10. Dependencies ### External Libraries * None. This session uses existing TypeScript, Zod, React, Tailwind CSS, Bun, and Vitest dependencies. ### Other Sessions * **Depends on**: `phase27-session01-brief-movement-groups-and-calibration-metrics`, `phase27-session04-daily-time-series-persistence-and-sparklines` * **Depended by**: `phase27-session12-documentation-validation-and-release` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase27-session10-demand-centers/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.