> 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/phase24-session06-signal-workbench-local-triage/spec.md). # Session Specification **Session ID**: `phase24-session06-signal-workbench-local-triage` **Phase**: 24 - Trend Finder Outlier Signal Upgrade **Status**: Not Started **Created**: 2026-06-08 *** ## 1. Session Overview This session adds a dense Signal Workbench to Trend Finder so an operator can scan every topic and its supporting evidence from one sortable, searchable, and filterable surface. Trends, Hidden Gems, Watchlist, Sources, and Brief already cover focused workflows, but none of them provide a global table-first review mode for repeated triage across all generated opportunities. The workbench is deliberately local-only. Triage states such as `acted-on`, `ignored`, and `revisit`, plus optional notes, are browser workflow annotations stored separately from generated Trend Finder data. They must not mutate source caches, topic scores, generated Watchlist rows, exported default payloads, or any script-side report output. This session builds on the Phase 24 scoring, enrichment, asset, source setup, and scheduler foundations. It should reuse existing Trend Finder schema projection, evidence asset badges, source health labels, runtime provenance, and visibility storage patterns while introducing a focused workbench model, storage contract, view, controls, and tests. *** ## 2. Objectives 1. Add a dedicated Signal Workbench tab with dense topic rows and expandable evidence rows for all Trend Finder topics. 2. Add search across topic names, summaries, creator angles, hooks, questions, evidence titles, snippets, and source names. 3. Add filters for source role, provenance, movement, hidden-gem state, score band, actionability band, runtime or fallback state, source health, and asset availability. 4. Add local-only triage states and notes with localStorage persistence, defensive parsing, duplicate-trigger prevention, and reset/revalidation on re-entry. 5. Add focused model, storage, component, accessibility, and documentation coverage proving triage never mutates generated Trend Finder output. *** ## 3. Prerequisites ### Required Sessions * [x] `phase24-session01-source-local-scoring-signals` - Provides source-local ratio, baseline, and actionability band fields used by workbench filters and evidence chips. * [x] `phase24-session03-browser-safe-evidence-assets-file-hardening` - Provides browser-safe evidence asset metadata and asset availability states used by workbench filters and expanded evidence rows. * [x] `phase24-session04-source-setup-target-configuration` - Provides source setup and source health state that informs source filters and degraded state labels. * [x] `phase24-session05-scheduler-first-run-live-progress-controls` - Provides runtime, scheduler, and live progress states that the workbench can summarize without exposing private run internals. ### Required Tools/Knowledge * Existing Trend Finder client tab registration in `src/extensions/trend-finder/client.tsx`. * Current topic, evidence, source summary, source-local signal, evidence asset, runtime, scheduler, and movement schema contracts. * Existing view-model helpers for ranked topics, source health, evidence links, movement labels, source-local metric chips, and asset preview labels. * Existing localStorage migration and visibility settings patterns. * Existing component test conventions using Vitest, Testing Library, and happy-dom. ### Environment Requirements * Bun 1.3.14 project toolchain from `.bun-version`. * React 19 with existing Tailwind CSS 4 and Radix/local component conventions. * Browser storage must use the `ai-os` storage prefix and preserve legacy compatibility only where a migration is explicitly defined. * Generated `src/data/live-data.json`, source caches, private snapshots, raw logs, prompts, provider responses, Actor inputs, Dataset rows, credentials, and local file paths must not be read or written by triage code. *** ## 4. Scope ### In Scope (MVP) * Trend Finder operators can open a Signal Workbench tab that renders all topics as dense rows with score, movement, novelty, evidence count, source diversity, top source role, published time, relative lift/actionability, and local triage state. * Trend Finder operators can expand a topic row to inspect supporting evidence rows, source labels, snippets, public links, source-local chips, and browser-safe asset availability states. * Trend Finder operators can search across topic name, summary, creator angle, hooks, questions, evidence title, evidence snippet, and source name. * Trend Finder operators can filter by source role, provenance, movement, hidden-gem state, score band, actionability band, runtime/fallback state, source health, asset availability, and triage state. * Trend Finder operators can sort by score, momentum, novelty, evidence count, movement, source diversity, source role, published time, relative lift, and triage state with deterministic tie-breaking. * Trend Finder operators can mark local triage state as `acted-on`, `ignored`, or `revisit`, add optional bounded notes, clear notes, and reset row state. * Local triage persists in browser localStorage under an `ai-os` key, parses defensively, bounds entry count and note length, drops malformed rows, and never changes generated Trend Finder payloads. * Trend Finder docs describe the Signal Workbench, local triage state, storage boundary, filters, sorting, and non-export behavior. ### Out of Scope (Deferred) * Mutating generated Watchlist rows or treating Watchlist as a manual bookmark list - *Reason: Watchlist remains generated from the current run.* * Writing local triage notes to source caches, topic scores, generated payloads, static exports, or script-side report output - *Reason: triage is a private browser workflow annotation.* * Adding a token-gated local file overlay for triage - *Reason: localStorage is sufficient for MVP and avoids a new write bridge in this session.* * Adding a marketing landing page or card-heavy replacement for the existing creator surfaces - *Reason: the required surface is a dense operator table.* * Adding new source adapters, source collection behavior, scoring formulas, or enrichment logic - *Reason: this session consumes existing generated data.* *** ## 5. Technical Approach ### Architecture Add a dedicated workbench model layer that consumes parsed `TrendFinderData` and produces stable row view models. The model should derive search text, filter facets, sort keys, evidence row summaries, source health labels, relative lift labels, actionability bands, score bands, movement order, asset availability, and deterministic row IDs without mutating the parsed payload. Add a local triage storage module around browser localStorage. The storage contract should use an `ai-os.trend-finder.signal-workbench.v1` key, provide defensive parse and serialize helpers, cap note length and stored rows, drop invalid states, dedupe by topic ID, and expose pure update helpers for `acted-on`, `ignored`, `revisit`, note edits, clears, and resets. Add a Signal Workbench view and focused components for toolbar filters, sortable headers, expandable rows, evidence details, and triage controls. Components should use native inputs, selects, checkboxes, buttons, and accessible status labels; busy states should disable duplicate actions; re-entry should reload or revalidate local storage so multiple tabs or stale state do not leave the UI lying. ### Design Patterns * Pure projection before UI: derive table rows and filter facets in testable functions before rendering components. * Local-only annotation boundary: triage state lives outside generated payloads and Watchlist semantics. * Typed degradation over blank states: missing data, fixture/demo provenance, disabled runtime, no assets, unknown health, and empty evidence render explicit labels. * Deterministic sorting: every sortable column uses a stable tie-breaker by rank, score, topic name, and topic ID. * Existing dense dashboard conventions: compact controls, fixed table dimensions, scannable text, and no nested cards. * Accessibility-first controls: sortable headers expose state, expanded rows are keyboard reachable, notes have bounded inputs, and status changes use polite live regions where useful. ### Technology Stack * TypeScript with React 19. * Tailwind CSS 4 and existing local component conventions. * Vitest, Testing Library, and happy-dom for model, storage, and component tests. * Browser localStorage through existing storage migration utilities. * Lucide React icons for tab and control affordances. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/trend-finder/signal-workbench-storage.ts` | Local triage storage contract, parser, serializer, and pure update helpers. | \~240 | | `src/extensions/trend-finder/signal-workbench-model.ts` | Workbench row projection, search, filter, sort, facet, and summary helpers. | \~420 | | `src/extensions/trend-finder/hooks/use-signal-workbench-triage.ts` | React hook for loading, persisting, resetting, and revalidating triage state. | \~180 | | `src/extensions/trend-finder/components/signal-workbench-controls.tsx` | Search, filter, density, and result summary controls. | \~240 | | `src/extensions/trend-finder/components/signal-workbench-table.tsx` | Dense sortable table with expandable evidence rows and accessible headers. | \~380 | | `src/extensions/trend-finder/components/signal-triage-controls.tsx` | Triage state buttons, bounded note editor, clear/reset controls, and live labels. | \~260 | | `src/extensions/trend-finder/views/signal-workbench-view.tsx` | Signal Workbench tab view wiring parsed data, model, controls, storage, and empty states. | \~300 | | `src/extensions/trend-finder/__tests__/signal-workbench-model.test.ts` | Tests for row projection, search, filters, sorting, facets, and payload immutability. | \~280 | | `src/extensions/trend-finder/__tests__/signal-workbench-storage.test.ts` | Tests for localStorage parsing, bounds, updates, dedupe, invalid drops, and serialization. | \~240 | | `src/extensions/trend-finder/components/__tests__/signal-workbench-view.test.tsx` | Component and accessibility tests for controls, sorting, expansion, triage, notes, and states. | \~320 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/trend-finder/client.tsx` | Register the Workbench tab, hero tagline, icon, and motion surface mapping. | \~30 | | `src/extensions/trend-finder/visibility-config.ts` | Add the workbench view ID and valid local UI ID prefixes if visibility controls are reused. | \~20 | | `src/extensions/trend-finder/visibility-menu-items.ts` | Add workbench visibility menu helpers only if the final Workbench view uses visibility controls. | \~50 | | `src/extensions/trend-finder/fixtures.ts` | Ensure fixtures cover source-local actionability, movement, asset availability, missing evidence, and varied source roles for workbench tests. | \~80 | | `docs/extensions/trend-finder-ui-surfaces.md` | Document Signal Workbench purpose, filters, sorting, local triage, storage boundary, and non-export behavior. | \~140 | | `docs/extensions/trend-finder-runtime-and-provenance.md` | Document that local triage is browser-only and excluded from generated payloads, source caches, and default exports. | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Signal Workbench is available as a Trend Finder tab and renders a dense table over all parsed topics with explicit loading, empty, error, and fixture/demo states. * [ ] Search covers topic name, summary, creator angle, hooks, questions, evidence title, evidence snippet, and source name. * [ ] Filters cover source role, provenance, movement, hidden-gem state, score band, actionability band, runtime/fallback state, source health, asset availability, and triage state. * [ ] Sorting covers score, momentum, novelty, evidence count, movement, source diversity, source role, published time, relative lift, and triage state with deterministic ordering. * [ ] Expanded rows expose evidence details, source labels, source-local chips, public evidence links, and browser-safe asset availability labels. * [ ] Local triage supports `acted-on`, `ignored`, `revisit`, optional bounded notes, clear, and reset without changing generated Trend Finder data. ### Testing Requirements * [ ] Unit tests written and passing for model projection, search, filters, sorting, facets, and immutable input behavior. * [ ] Unit tests written and passing for triage storage parsing, bounds, malformed rows, dedupe, note truncation, and update helpers. * [ ] Component tests written and passing for controls, sortable headers, expansion, triage state changes, note editing, loading, empty, and error states. * [ ] Manual testing completed on desktop and mobile breakpoints for table density, horizontal overflow, focus order, and text fit. ### Non-Functional Requirements * [ ] Workbench remains usable with fixture data, partial live data, missing evidence, disabled runtime states, unavailable assets, degraded sources, and empty topics. * [ ] Triage state is private browser state and is not included in default static export, generated payloads, source caches, Watchlist generation, logs, or script-side reports. * [ ] No new source collection, third-party transfer, credential handling, or bridge write path is introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Focused tests, app typecheck, lint, and docs formatting pass. *** ## 8. Implementation Notes ### Key Considerations * The generated Watchlist remains generated and read-only. Workbench triage is a separate local annotation model keyed by topic ID. * Workbench rows should derive from parsed Trend Finder data and never mutate topic, evidence, source, scheduler, runtime, or watchlist objects. * Missing fields must produce explicit labels such as "No evidence", "Unknown health", "No assets", or "Runtime unavailable" instead of blank table cells. * Search text should be normalized once per row so filtering remains predictable and testable. * Notes should be bounded and sanitized for display, but they should not be exported or written into generated payloads. ### Potential Challenges * Dense responsive layout: Use fixed column widths, horizontal overflow on narrow screens, and compact typography so text does not overlap controls. * Filter sprawl: Group related filters and provide clear reset behavior instead of rendering a long uncontrolled toolbar. * Large data sets: Precompute row summaries and search text with memoized projection helpers, then filter and sort arrays deterministically. * LocalStorage drift: Reload on mount and page visibility changes so stale triage annotations do not persist in memory after another tab changes them. ### Relevant Considerations * \[P02] **Extension payloads and demo labels stay bounded**: The workbench must keep live, fixture, fallback, degraded, and blocked states explicit while avoiding unbounded browser payload growth. * \[P02] **Static registry over dynamic loading**: The Workbench tab belongs in the static Trend Finder client registry, not a dynamic route loader. * \[P15] **Aggregate collection must stay budgeted**: The workbench consumes current generated summaries only and must not trigger collection or enrichment work. * \[P21] **Do not let token-shaped strings or auth headers reach browser state or logs**: Triage storage must never read or display credentials, tokens, raw logs, prompts, or private runtime paths. * \[P23] **Do not hand-edit generated route trees**: Register the extension tab through `client.tsx`; do not manually edit TanStack generated route files. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Triage actions accidentally mutating generated Watchlist or topic payloads. * Search/filter/sort controls losing deterministic state after reload, re-entry, or malformed localStorage content. * Dense table controls becoming inaccessible or unreadable on mobile and keyboard navigation paths. *** ## 9. Testing Strategy ### Unit Tests * Test `buildSignalWorkbenchRows`, search matching, filter combinations, score and actionability bands, source health facets, asset availability facets, deterministic sorting, and immutable input handling. * Test triage storage parsing, serialization, legacy/malformed input handling, note length bounds, row count bounds, dedupe, state transitions, clear, and reset behavior. ### Integration Tests * Test the Workbench view with fixture payloads for search, filters, sortable headers, expanded evidence rows, triage buttons, note editing, reset, and empty/error states. * Test that local triage changes do not alter parsed `TrendFinderData`, generated Watchlist rows, source summaries, or export-facing view models. ### Manual Testing * Open the Workbench tab from the Trend Finder sidebar and verify the first viewport is the actual table workflow, not a landing page. * Search for text from topic summaries, creator hooks, evidence snippets, and source names. * Combine multiple filters and then reset to verify the row count and focus behavior. * Expand rows, change triage state, add notes, reload, and confirm state persists only in browser localStorage. * Check desktop, tablet, and mobile widths for table overflow, text fit, focus order, and control usability. ### Edge Cases * No topics, no evidence, missing evidence IDs, no source summaries, unknown source roles, disabled runtime, fixture/demo data, unavailable/pruned assets, malformed localStorage JSON, oversized note input, duplicate topic triage rows, and multiple rows sharing the same sort key. *** ## 10. Dependencies ### External Libraries * No new external libraries are required. ### Other Sessions * **Depends on**: `phase24-session01-source-local-scoring-signals`, `phase24-session03-browser-safe-evidence-assets-file-hardening`, `phase24-session04-source-setup-target-configuration`, and `phase24-session05-scheduler-first-run-live-progress-controls`. * **Depended by**: `phase24-session07-static-brief-export`, `phase24-session08-cross-surface-documentation-reference-mode`, and `phase24-session09-end-to-end-validation-release-hardening`. *** ## 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/phase24-session06-signal-workbench-local-triage/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.