> 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-session09-competitor-lens-and-creator-angle-pack/spec.md). # Session Specification **Session ID**: `phase27-session09-competitor-lens-and-creator-angle-pack` **Phase**: 27 - Trend Finder Alpha Radar Adoption **Status**: Not Started **Created**: 2026-06-13 *** ## 1. Session Overview This session extends Trend Finder's Creator Lens with an optional bounded list of public competitor or adjacent-channel names, then carries that lens signal through collector-time YouTube evidence matching, browser-safe evidence flags, and visible chips in dense analysis surfaces. The change ports only the generalized Alpha Radar competitor-list capability, not its hardcoded single-creator profile. The same session also upgrades creator-facing analyst output with three copy-ready angle fields: a contrarian angle, a plain-language explainer, and a suggested title. These fields must be validated against the existing no-invented-metadata rules, generated deterministically when AI output is missing or invalid, and rendered on trend cards, the dashboard Brief, and the static Brief export. This is the first Phase 27 Tier 3 session. Sessions 1-8 completed the deterministic and history-backed foundations that make these richer creator signals safer to expose. Session 11 depends on the analyst prompt-extension pattern established here. *** ## 2. Objectives 1. Add a bounded `competitors` field to Creator Lens storage, saved config, bridge validation, draft UI, and save/rerun flow. 2. Flag YouTube evidence whose public channel-title entity matches the saved competitor list, with browser-safe schema defaults and visible evidence chips. 3. Extend analyst prompt, output schema, validation, and deterministic fallback with `contrarianAngle`, `plainExplainer`, and `suggestedTitle`. 4. Render a copy-ready angle block on trend cards, dashboard Brief, and static Brief output while preserving legacy payload parsing. *** ## 3. Prerequisites ### Required Sessions * [x] `phase27-session03-data-driven-radar-aliases-and-watching-state` - Workbench chip/filter patterns and browser-local triage state are available. * [x] `phase27-session08-dated-predictions-and-story-log` - Current Phase 27 schema, Brief, prediction, and validation patterns are in place. ### Required Tools/Knowledge * Bun 1.3.14, TypeScript, Vitest, and the existing Trend Finder script test harness. * Zod additive default patterns in `src/extensions/trend-finder/schema.ts`. * Fail-closed local bridge pattern in `scripts/lib/trend-finder-lens-bridge.ts`. * Analyst validation and deterministic fallback patterns in `scripts/lib/ai-runtime/trend-analyst.ts` and collector fallback paths. ### Environment Requirements * No live AI runtime credentials are required; fallback parity must be testable without external services. * YouTube source compliance remains limited to reviewed public video metadata and public channel titles. * Generated private Trend Finder snapshots and cache artifacts stay out of git. *** ## 4. Scope ### In Scope (MVP) * Creator config editors can save a bounded public competitor or adjacent channel list - Implement through lens schema, browser draft storage, saved config, and bridge validation with count and string-length caps. * Trend Finder collector can flag competitor-matched YouTube evidence - Match normalized public channel-title entities to the saved lens list at collect time. * Analysts receive and return richer creator angle fields - Extend prompt, schema hint, validator, and repair behavior for contrarian, plain-language, and title fields. * Deterministic fallback produces all new angle fields - Compose output from lens format, topic names, and cited evidence without inventing sources, dates, metrics, or URLs. * Operators can see and copy the angle pack - Render compact copy-ready blocks on cards, dashboard Brief, and static Brief projection/rendering. * Focused tests cover lens parsing/migration, bridge rejection, competitor matching, analyst validation, fallback output, UI rendering, and legacy payload parsing. ### Out of Scope (Deferred) * Competitor matching beyond reviewed public channel-title entities - *Reason: source compliance approves public YouTube video metadata only; no author identity grouping is introduced.* * Hardcoded creator profiles - *Reason: Trend Finder's Creator Lens is the generalized contract.* * Per-outlier creator ideas - *Reason: Session 11 owns top-N outlier ideas and enrichment-cache behavior.* * New public source adapters or new source calls - *Reason: source expansion requires compliance-first review in a future phase.* *** ## 5. Technical Approach ### Architecture The Creator Lens contract changes additively at the shared browser schema boundary first, then mirror the same limits in browser draft storage and the script-side saved config validator. The lens bridge continues to require loopback access, the same-run token, maximum body size, and strict payload validation before writes. Collector-side competitor matching stays script-only. Normalized YouTube source-local channel entities are compared against a normalized, deduplicated competitor set from the saved Creator Lens. Matching adds bounded evidence-level metadata to both generated browser evidence and analyst input, without exposing raw source payloads or private paths. Angle-pack fields follow the existing analyst output path: prompt/schema hint, Zod validation, citation/invented-metadata checks, repair retry, and fallback when output is invalid. Browser UI consumes only validated schema fields through view models and static Brief projection. ### Design Patterns * Additive schema defaults: Legacy payloads without new lens, evidence, or topic fields keep parsing. * Fail-closed bridge validation: Unknown or oversized lens writes are rejected before persistence. * Script-only runtime boundary: Matching and fallback composition stay under `scripts/`; browser code renders validated fields. * Project before rendering: Static Brief receives new angle fields through `static-brief-export.ts`, not raw payload reads. * Deterministic ordering: Competitor list normalization and evidence chips use stable lowercase keys and sorted display where appropriate. ### Technology Stack * TypeScript with strict local contracts. * Zod for runtime schemas and additive defaults. * React 19, TanStack route surfaces, Tailwind CSS 4, and lucide-react icons for UI. * Bun and Vitest for focused script and component tests. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------- | | `scripts/extensions/trend-finder/competitor-matching.ts` | Normalize competitor names and flag matching YouTube channel-title entities. | \~140 | | `scripts/extensions/trend-finder/__tests__/competitor-matching.test.ts` | Focused tests for normalization, bounds, matching, and non-YouTube exclusions. | \~140 | ### Files to Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/trend-finder/schema.ts` | Add lens competitors, evidence competitor match metadata, topic angle-pack fields, and additive defaults. | \~120 | | `src/extensions/trend-finder/creator-lens-storage.ts` | Normalize, persist, and migrate competitor list draft values. | \~90 | | `src/extensions/trend-finder/hooks/use-creator-lens-draft.ts` | Add draft controls and dirty-state support for competitor list edits. | \~60 | | `src/extensions/trend-finder/components/creator-lens-panel.tsx` | Add accessible competitor-list editor and validation feedback. | \~80 | | `scripts/lib/ai-runtime/creator-lens-config.ts` | Add saved config validation limits and strict unknown-field rejection coverage for competitors. | \~90 | | `scripts/lib/trend-finder-lens-bridge.ts` | Preserve bridge boundary behavior while returning competitor diagnostics. | \~20 | | `scripts/extensions/trend-finder/sources/apify-normalizers.ts` | Carry competitor match metadata through normalized YouTube evidence. | \~60 | | `scripts/extensions/trend-finder/collector.ts` | Apply competitor matching and ensure scored/fallback topics carry new angle fields. | \~110 | | `scripts/extensions/trend-finder/topics.ts` | Extend deterministic fallback topics with angle-pack placeholders derived from lens and evidence. | \~80 | | `scripts/lib/ai-runtime/trend-analyst.ts` | Extend prompt, schema hint, output validator, grounding checks, and fallback acceptance. | \~140 | | `src/extensions/trend-finder/view-model.ts` | Project competitor chips and angle-pack copy for cards, Brief, and evidence rows. | \~80 | | `src/extensions/trend-finder/components/evidence-links.tsx` | Render competitor evidence chips with accessible labels. | \~40 | | `src/extensions/trend-finder/components/signal-workbench-table.tsx` | Surface competitor evidence flags in expanded evidence rows. | \~35 | | `src/extensions/trend-finder/components/trend-card.tsx` | Render copy-ready angle block with title, contrarian angle, and plain explainer. | \~70 | | `src/extensions/trend-finder/views/brief-view.tsx` | Render angle pack on Brief opportunity cards. | \~60 | | `scripts/extensions/trend-finder/static-brief-export.ts` | Project angle-pack and competitor-safe evidence fields into static report rows. | \~70 | | `scripts/extensions/trend-finder/static-brief-renderer.ts` | Render copy-ready static Brief angle block and evidence chips. | \~70 | | `scripts/lib/__tests__/trend-finder-lens-bridge.test.ts` | Add bridge rejection and saved competitor payload tests. | \~80 | | `scripts/lib/ai-runtime/__tests__/creator-lens-config.test.ts` | Add saved config normalization, cap, and legacy migration tests. | \~80 | | `scripts/lib/ai-runtime/__tests__/trend-analyst.test.ts` | Add angle-pack validation, invented-content rejection, and legacy output tests. | \~110 | | `scripts/extensions/trend-finder/__tests__/collector.test.ts` | Add collector matching and fallback angle-pack coverage. | \~110 | | `src/extensions/trend-finder/__tests__/view-model.test.ts` | Add competitor chip and angle-pack projection tests. | \~80 | | `src/extensions/trend-finder/components/__tests__/signal-workbench-view.test.tsx` | Add Workbench competitor evidence chip rendering coverage. | \~60 | | `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts` | Add static projection and privacy-safe angle-pack tests. | \~90 | | `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Add static HTML rendering tests for copy-ready blocks and chips. | \~70 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Saved Creator Lens competitor lists affect the next collector run only; browser drafts remain local until saved. * [ ] Lens bridge rejects oversized lists, malformed names, unknown fields, and missing or invalid tokens. * [ ] Competitor flags appear only on evidence whose public YouTube channel-title entity matches a configured competitor name. * [ ] Analyst output validates `contrarianAngle`, `plainExplainer`, and `suggestedTitle`; invalid or missing output falls back deterministically with warnings. * [ ] Legacy payloads and saved lens configs without new fields keep parsing. ### Testing Requirements * [ ] Focused unit tests cover lens storage, saved config, bridge validation, competitor matching, analyst validation, collector fallback, view models, and static Brief projection. * [ ] Component tests cover Creator Lens editor, card/Brief angle blocks, evidence chips, and Workbench evidence rows. * [ ] Manual validation covers draft edit, save, rerun contract, and copy-ready output on Trends and Brief. ### Non-Functional Requirements * [ ] Browser-visible payload remains bounded under the shared 1 MB extension payload limit. * [ ] No raw prompts, provider responses, local paths, tokens, Actor inputs, or raw source payloads enter browser state or static export. * [ ] YouTube compliance boundary remains public metadata only. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run typecheck:scripts` passes. * [ ] Focused Vitest suites for changed files pass. *** ## 8. Implementation Notes ### Key Considerations * Use one shared competitor normalizer for browser storage, saved config, and collector matching so cap and dedupe behavior cannot drift. * Keep competitor matching evidence-level, not topic-level, then derive topic summaries through view models. * Limit competitor list count and item length before persistence and before collector matching. * Avoid introducing any new source call; all matching uses already-normalized public YouTube channel-title metadata. ### Potential Challenges * Lens contract drift between browser and script code: Mitigate with mirrored tests around storage and saved config plus shared expected fixtures. * Analyst prompt creep: Mitigate by adding three required fields only and preserving one repair retry plus deterministic fallback. * UI density: Mitigate by rendering compact copy blocks and truncation-safe chips rather than expanding the whole card layout. * Static export privacy: Mitigate through projection in `static-brief-export.ts` and renderer tests over sanitized output. ### Relevant Considerations * \[P02] **Extension payloads and demo labels stay bounded**: New arrays and strings get explicit caps and additive defaults. * \[P02] **New source adapters need per-source compliance review**: This session uses only reviewed YouTube public metadata and adds no source adapter. * \[P15] **Aggregate collection must stay budgeted**: New AI prompt fields must degrade to fallback instead of requiring additional calls. * \[P24] **Fail-closed bridges need boundary validation**: Creator Lens bridge changes preserve loopback, token, body-size, and schema checks. * \[P24] **Additive defaults keep legacy payloads alive**: New fields use defaults so fixtures and historical payloads keep parsing. * \[P24] **Project before rendering**: Static Brief output receives new copy through projection, not raw payload reads. * \[P05] **Script-only runtime boundary**: Matching and fallback composition stay under script/runtime modules; browser renders validated data only. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Duplicate saves or reruns could persist half-normalized lens state. * Invalid AI angle output could leak invented metadata unless validator and fallback paths cover every new string field. * Revisited lens panels and Brief/cards could show stale draft or copy state if re-entry resets are incomplete. *** ## 9. Testing Strategy ### Unit Tests * Creator Lens browser storage normalization, migration, dedupe, caps, and malformed payload fallback. * Saved Creator Lens config validation, strict unknown-field rejection, and bridge diagnostics. * Competitor matching helper normalization, YouTube-only matching, case and whitespace handling, and non-match behavior. * Analyst output schema and invented-metadata validation for new angle fields. * Collector fallback output for deterministic angle pack fields. ### Integration Tests * Collector path from saved lens through normalized evidence, scored topics, browser schema parse, and view-model projection. * Static Brief export path from Trend Finder data through projected report and rendered HTML. ### Manual Testing * Edit competitor list in Creator Lens, confirm draft-only behavior, save, run the collector, and verify matching evidence chips in Trends, Workbench, and Brief. * Force analyst fallback or invalid output and verify angle-pack fields still render with fallback provenance warnings. ### Edge Cases * Empty competitor list, duplicate names, long names, punctuation differences, and case-only duplicates. * Non-YouTube evidence with matching text must not receive competitor flags. * Legacy saved lens config and browser payloads without `competitors` parse to defaults. * Copy-ready blocks handle missing optional strings without layout shifts. *** ## 10. Dependencies ### External Libraries * None. Use existing TypeScript, Zod, React, lucide-react, Tailwind, Bun, and Vitest stack. ### Other Sessions * **Depends on**: `phase27-session03-data-driven-radar-aliases-and-watching-state`, `phase27-session08-dated-predictions-and-story-log` * **Depended by**: `phase27-session11-theme-rollups-and-outlier-ideas`, `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-session09-competitor-lens-and-creator-angle-pack/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.