> 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/phase29-session14-one-to-watch-surface/spec.md). # Session Specification **Session ID**: `phase29-session14-one-to-watch-surface` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-21 *** ## 1. Session Overview This session adds a dedicated One-to-Watch surface over Trend Finder's existing prediction, retro, calibration, reception, and corroboration data. It turns the current prediction loop into a scannable "what to watch next cycle" readout without adding a new prediction model, source collector, or invented accuracy claim. The session fits Phase 29's Tier 3 operator-polish work. Sessions 03 and 04 already shipped the aggregate-only reception signal and corroboration gate that can help rank and explain watch rows. The implementation should reuse those fields where available, keep deterministic fallbacks, and clearly label unknown or uncalibrated accuracy instead of publishing mock accuracy chips. The browser-facing work should be compact and operational. A small Trends dashboard strip gives operators a first-viewport forward-looking cue, the Brief tab provides the fuller creator-facing summary, and the static Brief exports the same bounded rows for local share/review artifacts. *** ## 2. Objectives 1. Project One-to-Watch rows from existing prediction, retro, calibration, and current topic records. 2. Rank forward-looking watch rows with deterministic, bounded rules that use evidence, prediction direction, reception, and corroboration when present. 3. Render explicit unknown or uncalibrated accuracy labels and never show mock hit-rate or accuracy chips. 4. Surface One-to-Watch rows in Trends, Brief, and static Brief outputs with accessible, responsive presentation. 5. Prove rendering, ranking, missing-calibration honesty, privacy, payload, and browser-visible behavior with focused tests. *** ## 3. Prerequisites ### Required Sessions * [x] `phase29-session03-reception-signal-aggregate-only` - Provides aggregate-only reception fields that can inform watch-row explanation without comment-body reads. * [x] `phase29-session04-corroboration-gate` - Provides corroboration fields that distinguish better-supported candidates from originator-only rows. * [x] `phase29-session13-static-brief-archival-and-richness` - Provides the current static Brief projection, renderer, archival, QA, and local report baseline. ### Required Tools/Knowledge * Bun 1.3.14 workflow through `bun run test`. * Existing Trend Finder prediction and retro modules under `scripts/lib/ai-runtime/`. * Existing `predictionRetroSummary` schema, view-models, and UI panels. * Existing prediction, retro, calibration, and Story Log summaries in current generated data contracts. * Static Brief export, renderer, QA, and Playwright static Brief tests. * Current payload, browser-safety, and private-artifact scan constraints. ### Environment Requirements * Project dependencies installed with Bun. * Fixture or generated Trend Finder payload that includes prediction/retro summary rows. * No new source, media, credential, database, dependency, hosted storage, or third-party transfer approval is required. *** ## 4. Scope ### In Scope (MVP) * Operators can see a One-to-Watch strip in Trends - Build compact first-viewport rows from existing prediction records and current topic context. * Brief readers can scan next-cycle watch rows - Add a fuller Brief section with prediction direction, watch-next copy, support labels, and calibration honesty. * Static Brief readers get the same bounded rows - Project and render One-to-Watch rows in the local standalone report. * Existing records drive ranking - Use prediction direction, watch-next copy, current score/evidence, reception state, corroboration state, and retro calibration when present. * Missing calibration is explicit - Show "Uncalibrated", "Accuracy unknown", or the existing unavailable reason rather than fabricated percentages. * Browser-safe boundaries hold - Keep prompts, provider responses, raw rows, private paths, raw logs, tokens, comments, transcripts, and local triage notes out of UI/export output. * Tests prove honest output - Cover ranking, empty states, missing calibration, no mock chips, renderer escaping, static Brief output, and responsive UI. ### Out of Scope (Deferred) * New prediction model, classifier, or AI prompt - Reason: this session is presentation over existing records only. * New next-cycle claims beyond stored predictions - Reason: invented claims are explicitly prohibited. * Mock accuracy, "100% hit rate", or placeholder confidence chips - Reason: calibration honesty is a do-not-regress guardrail. * New source collection, social media, comments, podcasts, transcripts, or media embeds - Reason: source and media boundaries remain compliance-gated. * Durable database or hosted report storage - Reason: current history remains local archive and static Brief output. * Podcast compliance or podcast-themes work - Reason: Sessions 16 and 17 own that boundary. *** ## 5. Technical Approach ### Architecture Add One-to-Watch projection logic beside the existing prediction/retro view-models in `src/extensions/trend-finder/view-model.ts`. The projection should accept the parsed Trend Finder payload, derive rows from `predictionRetroSummary.storyLog` and `recentPredictions`, join current topic context by canonical topic ID when available, and return bounded rows with sanitized strings, accessible labels, explicit accuracy state, support labels, and deterministic ranking. The ranking is a presentation rank, not a model. Prioritize rows that are still forward-looking or not-yet-due, have watch-next/rationale copy, map to a current topic with evidence, have stronger corroboration, and avoid suppressed or single-origin caveats unless no stronger rows exist. If calibration has no resolved records, every row must carry an unknown or uncalibrated accuracy label. If calibration is available, only show aggregate calibration labels, not per-row accuracy invented from unrelated records. Wire the projection into `TrendsView` as a compact dashboard panel, into `BriefView` as the main creator-facing section, into `brief-export-model.ts` for Markdown/JSON copy exports, and into `static-brief-export.ts` plus `static-brief-renderer.ts` for local static HTML. All exported rows must pass the same strict schema and private-string filtering style as existing Brief and static Brief projections. ### Design Patterns * Browser-safe projection: UI and renderers consume bounded view-model fields, not raw archive records. * Deterministic ordering: rank by due state, support signals, score/evidence, generated date, and stable IDs. * Calibration honesty: labels describe aggregate calibration availability, never per-row mock accuracy. * Additive panel: no route migration or existing prediction/retro behavior removal. * Existing visibility controls: new panels participate in per-view hide/restore behavior. * Fail closed on unsafe export: static Brief schema and QA reject unsafe output before promotion. ### Technology Stack * TypeScript for app, view-model, export, and renderer code. * React 19 and existing Tailwind CSS 4 conventions for Trends and Brief UI. * Zod strict schemas for static Brief report projection. * Bun and Vitest for unit/component tests. * Playwright for browser-visible static Brief and Trend Finder checks. *** ## 6. Deliverables ### Files to Create No standalone production files are required. The work extends existing Trend Finder projection, UI, export, renderer, test, and documentation files. ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------- | | `src/extensions/trend-finder/view-model.ts` | Add One-to-Watch view-model types, ranking, labels, empty states, and topic joins. | \~220 | | `src/extensions/trend-finder/views/trends-view.tsx` | Add compact first-viewport One-to-Watch panel and visibility menu item. | \~120 | | `src/extensions/trend-finder/views/brief-view.tsx` | Add fuller Brief One-to-Watch section and visibility menu item. | \~150 | | `src/extensions/trend-finder/brief-export-model.ts` | Add One-to-Watch rows to copy/export Markdown and JSON projection. | \~120 | | `scripts/extensions/trend-finder/static-brief-export.ts` | Add strict One-to-Watch static report schema and projection. | \~130 | | `scripts/extensions/trend-finder/static-brief-renderer.ts` | Render One-to-Watch static Brief section with escaped text and empty states. | \~120 | | `src/extensions/trend-finder/__tests__/view-model.test.ts` | Cover rank ordering, support labels, and missing calibration honesty. | \~140 | | `src/extensions/trend-finder/views/__tests__/brief-view.test.tsx` | Cover Brief section rendering, empty state, and no mock accuracy copy. | \~120 | | `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts` | Cover static projection bounds and unknown calibration labels. | \~90 | | `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Cover static HTML rendering, escaping, empty state, and no unsafe links. | \~90 | | `tests/e2e/trend-finder.spec.ts` | Cover Trends compact panel desktop/mobile visibility and no overflow. | \~80 | | `tests/e2e/trend-finder-static-brief.spec.ts` | Cover static Brief One-to-Watch section and private-string cleanliness. | \~70 | | `docs/extensions/trend-finder-ui-surfaces.md` | Document live One-to-Watch behavior and calibration honesty. | \~60 | | `docs/extensions/trend-finder-history.md` | Document how predictions/retros feed One-to-Watch without per-row accuracy claims. | \~60 | | `docs/extensions/trend-finder-pipeline.md` | Document static Brief projection and payload/privacy expectations. | \~50 | *** ## 7. Success Criteria ### Functional Requirements * [ ] One-to-Watch rows render from existing prediction and Story Log records. * [ ] Rows rank deterministically using available prediction, evidence, reception, corroboration, and current topic context. * [ ] Missing calibration is labeled explicitly and never represented as an accuracy percentage. * [ ] No invented next-cycle claims or mock accuracy chips are published. * [ ] Trends, Brief, copy/export, and static Brief surfaces show consistent row labels and empty states. * [ ] Browser-safe and static export outputs exclude raw rows, private paths, prompts, provider responses, tokens, comments, transcripts, and local triage notes. ### Testing Requirements * [ ] Unit tests written and passing for One-to-Watch ranking and label logic. * [ ] Component tests written and passing for Brief rendering and missing calibration honesty. * [ ] Static Brief export and renderer tests prove bounded rows, escaping, empty states, and no unsafe links. * [ ] Playwright checks cover Trends and static Brief browser-visible output. * [ ] Manual testing completed for Trends, Brief, and static Brief report output. ### Non-Functional Requirements * [ ] Existing 1 MB Trend Finder browser payload budget remains green. * [ ] Static Brief private-string scan remains green. * [ ] UI remains dense, responsive, keyboard reachable, and free of document horizontal overflow on mobile. * [ ] No new dependency, source, credential, hosted storage, database schema, or third-party transfer is introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run test` or focused test equivalents pass. * [ ] `bun run typecheck` and script type checks pass for touched code. *** ## 8. Implementation Notes ### Key Considerations * The row ranking is a deterministic presentation sort, not a predictive model. * Aggregate calibration may be shown as context, but per-row accuracy must not be inferred unless a real resolved record supports it. * The static Brief report contract should stay strict, bounded, and sanitized. * The Trends panel should be compact enough not to bury the ranked trends, source state, provenance, or run controls. ### Potential Challenges * Joining current topic context to older prediction records: Use canonical topic IDs first, then stable topic IDs, and fall back to prediction text only. * Missing prediction archives in older payloads: Return a clear empty state and keep existing `archivePresent` behavior. * Calibration wording confusion: Use explicit labels like "Accuracy unknown" or "Uncalibrated" rather than percentages when resolved retros are absent. * Static Brief schema churn: Add defaults and bounded arrays so older report fixtures and generated data continue to parse. ### Relevant Considerations * \[P02] **Extension payloads and labels stay bounded**: Keep One-to-Watch rows bounded and preserve explicit unavailable states. * \[P24] **Browser-safe export and triage boundaries**: Do not leak local triage notes, private paths, raw evidence, prompts, provider responses, or browser-storage keys into Brief or static Brief output. * \[P27] **Deterministic fallback before AI enrichment**: This session is deterministic projection only; no AI-generated replacement claims. * \[P28] **Trend Finder release validation is bundled**: Record payload, static Brief, privacy, and browser checks during implementation/validation. * \[P00] **Do not document planned features as implemented**: Update docs only for actual shipped behavior during implementation. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Mock or misleading accuracy claims appearing when calibration is unavailable. * One-to-Watch rows leaking raw archive/source/private strings into UI or static output. * Added panels causing mobile overflow or burying the primary trend surface. *** ## 9. Testing Strategy ### Unit Tests * One-to-Watch rank ordering for forward-looking rows, not-yet-due rows, topic support, reception/corroboration context, and deterministic ties. * Accuracy label behavior for unavailable calibration, available aggregate calibration, stale pending rows, and empty archives. * Static Brief projection limits, strict schema defaults, and safe text bounds. ### Integration Tests * Brief view renders One-to-Watch rows, explicit unknown calibration labels, and empty states from fixture data. * Static Brief export and renderer include One-to-Watch rows while escaping text and filtering unsafe/private output. * Copy/export Markdown and JSON include the same bounded rows and honest labels. ### Manual Testing * Open `/extensions/trend-finder/trends` and confirm the compact panel is visible without pushing ranked trend scanning below the first viewport. * Open `/extensions/trend-finder/brief` and confirm One-to-Watch reads as a creator-facing next-cycle section. * Generate or fixture-render a static Brief and confirm One-to-Watch is present, bounded, and privacy-clean. ### Edge Cases * No prediction archive. * Predictions exist but no resolved retros. * Story Log contains stale pending or not-yet-due rows. * Current topic no longer exists for an older prediction. * Long topic names, watch-next copy, rationale, or unavailable reason. * Suppressed or originator-only current topic context. *** ## 10. Dependencies ### External Libraries * No new external libraries. ### Other Sessions * **Depends on**: `phase29-session03-reception-signal-aggregate-only`, `phase29-session04-corroboration-gate`, `phase29-session13-static-brief-archival-and-richness`. * **Depended by**: `phase29-session18-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/phase29-session14-one-to-watch-surface/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.