> 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/phase28-session09-action-queue-surface/spec.md). # Session Specification **Session ID**: `phase28-session09-action-queue-surface` **Phase**: 28 - Trend Finder Trends-Finderz Adoption **Status**: Not Started **Created**: 2026-06-14 *** ## 1. Session Overview This session turns the Session 08 topic-level action verdicts into a decision-oriented Trend Finder surface. The existing Trend Finder Brief explains what moved, what to pick today, demand centers, prediction history, source health, creator angles, and evidence. It still lacks a compact answer to the operator question "what should I do next?" The MVP adds a fourth Brief section named Decisions that groups topics by the existing `act_now`, `monitor`, `review`, and `ignore` verdicts. Each group shows counts, top topics, action reasons, QA caution state, and explicit unavailable copy when verdict data is absent. This should make the Brief a scannable handoff without adding a standalone route. The session also carries the Decisions section into the static Brief export through the existing projection layer, never through raw payload reads. If it fits within the session, Signal Workbench gains a verdict-grouped preset that uses stable ordering and existing row state rather than adding write or triage actions. *** ## 2. Objectives 1. Add a deterministic Decisions Brief view model grouped by action verdict with counts, top reasons, QA caution summaries, and unavailable state. 2. Render the Decisions section inside the existing Brief surface with dense, accessible, mobile-safe layout and visibility-menu integration. 3. Project and render the Decisions section in the static Brief export through `projectStaticBriefReport`, with no raw topic payload reads in the renderer. 4. Add an optional Signal Workbench verdict preset with deterministic ordering, bounded filters, and tests for stable reset behavior. *** ## 3. Prerequisites ### Required Sessions * [x] `phase28-session08-action-verdicts-and-consistency-qa` - provides per-topic action recommendations, verdict labels, reasons, QA status, and creator-angle caution view-model fields to group. * [x] `phase24-session07-static-brief-export` - provides the static Brief projection and renderer pipeline this session extends. * [x] `phase24-session06-signal-workbench-local-triage` - provides the Signal Workbench row, filter, preset, and sorting patterns used by the optional verdict preset. * [x] `phase27-session01-brief-movement-groups-and-calibration-metrics` - provides the Brief grouping pattern this session should follow. ### Required Tools/Knowledge * Bun 1.3.14 package/runtime commands. * TypeScript, Zod, Vitest, React 19, Tailwind CSS 4, and existing `@/` path aliases. * Existing Trend Finder schema, view-model, Brief view, static Brief export, Signal Workbench, fixture, and test patterns. * Trends-Finderz reference files: `EXAMPLES/trends-finderz/lib/trends/action-queue.ts`, `EXAMPLES/trends-finderz/components/action-queue/ActionQueueView.tsx`, and `EXAMPLES/trends-finderz/app/action-queue/page.tsx`. ### Environment Requirements * Run commands from the repository root. * Keep generated private runtime data, traces, screenshots, source dumps, and cache artifacts out of commits. * Do not add source adapters, network calls, analyst calls, dependencies, hosted storage, write-capable verdict actions, or a new Action Queue route. *** ## 4. Scope ### In Scope (MVP) * Trend Finder can group Brief topics by the existing action verdicts: `act_now`, `monitor`, `review`, and `ignore`. * Trend Finder can show per-group counts, top topic rows, top action reasons, urgency/score context, and QA caution summaries. * Trend Finder can render an explicit unavailable or degraded Decisions state when legacy payloads or empty topic sets do not contain usable verdict data. * The static Brief export can include the Decisions section through a projected report schema field and renderer helper. * Signal Workbench can optionally expose a verdict-grouped preset with stable ordering by verdict priority, action score, topic rank, and topic ID. * Tests cover grouping/counts, reason ordering, unavailable states, static export projection and rendering, and Workbench preset ordering. ### Out of Scope (Deferred) * Standalone `/action-queue` route or new full-page Action Queue view - *Reason: the PRD prefers the Brief section first unless it proves cramped.* * Changing verdict logic, caps, reason generation, or QA demotion - *Reason: Session 08 owns verdict computation.* * Browser-local writes, triage actions, pins, notes, tags, or saved queue state * *Reason: Session 10 owns pin metadata and notes/tags.* * New collector fields, source adapters, AI calls, or runtime dependencies - *Reason: this session presents existing verdict data.* * Raw payload access from the static renderer - *Reason: export privacy depends on projection before rendering.* *** ## 5. Technical Approach ### Architecture Add a Brief Decisions view model in `src/extensions/trend-finder/view-model.ts` that consumes `TopicCardViewModel[]` and returns a bounded set of verdict groups. The helper should reuse Session 08 action recommendation and QA labels instead of deriving new semantics. Group order should be stable: `act_now`, `monitor`, `review`, then `ignore`. Within each group, topics should sort by action score, urgency priority, topic rank, and topic ID. Extend `brief-view.tsx` with a new Decisions section that follows the existing movement-group and panel visibility patterns. The section should stay dense and scannable: group cards or rows, counts, short labels, top reasons, selected topic names, and caution summaries. It must not become a marketing-style page or standalone route. Extend `scripts/extensions/trend-finder/static-brief-export.ts` with a projected `decisions` field in `StaticBriefReportSchema`, populated from the same grouping semantics. Extend `static-brief-renderer.ts` to render only that projected field. The renderer should not inspect raw topic payloads. For the optional Workbench preset, extend the existing Workbench model and controls with an action-verdict preset/filter/sort path. The preset should remain read-only and must reset or revalidate state when the row signature changes, matching current Workbench behavior. ### Design Patterns * Project before rendering: static export receives a narrowed Decisions model before HTML rendering. * Existing enum labels only: reuse Session 08 verdict labels, tones, reason labels, and QA labels. * Explicit unavailable state: legacy payloads and empty reports get copy, not blank groups. * Dense dashboard UI: compact operational rows, familiar chips, stable dimensions, and no new route unless a later session proves the Brief is cramped. * Existing component patterns: 8px-or-less radii where possible, Tailwind CSS utility styling, accessible labels, keyboard focus support, and no layout shift. ### Technology Stack * Bun 1.3.14 for scripts and test execution. * TypeScript for application and script code. * Zod for static export report schema parsing. * React 19 and Tailwind CSS 4 for existing Brief and Workbench surfaces. * Vitest and Testing Library for view-model, renderer, Workbench, and Brief component coverage. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------- | | `src/extensions/trend-finder/views/__tests__/brief-view.test.tsx` | Browser-visible Decisions section render, unavailable state, and labels | \~180 | | `.spec_system/specs/phase28-session09-action-queue-surface/implementation-notes.md` | Record grouping choices, validation commands, screenshots, and risks | \~70 | ### Files to Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------- | | `src/extensions/trend-finder/view-model.ts` | Add Decisions grouping types, helper, reason counts, and unavailable copy | \~180 | | `src/extensions/trend-finder/views/brief-view.tsx` | Render Decisions Brief section and visibility-menu item | \~180 | | `scripts/extensions/trend-finder/static-brief-export.ts` | Add projected Decisions schema and report projection | \~170 | | `scripts/extensions/trend-finder/static-brief-renderer.ts` | Render projected Decisions section in static HTML | \~120 | | `src/extensions/trend-finder/signal-workbench-model.ts` | Add optional verdict preset/filter/sort support | \~140 | | `src/extensions/trend-finder/components/signal-workbench-controls.tsx` | Add preset control with accessible toggle labels | \~70 | | `src/extensions/trend-finder/views/signal-workbench-view.tsx` | Wire verdict preset sort/reset behavior | \~60 | | `src/extensions/trend-finder/fixtures.ts` | Ensure fixtures cover all verdict groups and legacy unavailable state | \~80 | | `src/extensions/trend-finder/__tests__/view-model.test.ts` | Cover Decisions grouping, counts, reasons, order, and unavailable state | \~120 | | `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts` | Cover static projection and report schema parsing | \~100 | | `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Cover static HTML rendering and no raw payload dependency | \~100 | | `src/extensions/trend-finder/__tests__/signal-workbench-model.test.ts` | Cover verdict preset filtering and deterministic ordering | \~90 | | `src/extensions/trend-finder/components/__tests__/signal-workbench-view.test.tsx` | Cover preset control behavior and reset on row changes | \~100 | *** ## 7. Success Criteria ### Functional Requirements * [ ] The Brief shows a Decisions section grouped by Act now, Monitor, Review, and Ignore with counts, top topics, reasons, and QA caution summaries. * [ ] Legacy or missing verdict data renders explicit unavailable copy, not empty groups or misleading zero-count decisions. * [ ] The static Brief export renders Decisions through the projected report model and never reads raw topic payload fields inside the renderer. * [ ] The optional Signal Workbench preset groups or filters by verdict with deterministic ordering and no write-capable action state. * [ ] The standalone Action Queue route remains deferred and documented only as a follow-up if the Brief section proves cramped. ### Testing Requirements * [ ] Unit tests written and passing for Decisions view-model grouping, counts, reason ordering, QA caution summaries, and unavailable state. * [ ] Static export projection and renderer tests written and passing. * [ ] Workbench preset model and UI tests written and passing if the optional preset is implemented. * [ ] Manual Brief checks completed for desktop and mobile widths. ### Non-Functional Requirements * [ ] No verdict logic, source collection, AI calls, dependencies, credential paths, hosted storage, or write-capable surfaces are introduced. * [ ] Decisions arrays and reason summaries are bounded to protect the shared 1 MB extension payload limit and static export size. * [ ] Static export keeps local triage notes, private paths, raw evidence dumps, prompts, and provider responses out of browser-visible output. * [ ] UI remains dense, scannable, accessible, and mobile-safe. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Focused view-model, Brief view, static export, renderer, and Workbench tests pass. * [ ] `bun run test` passes or any unrelated repo-wide failures are documented. *** ## 8. Implementation Notes ### Key Considerations * Session 08 uses internal verdict enum values `act_now`, `monitor`, `review`, and `ignore`; this session should display those through existing labels rather than introducing `act/watch/research/skip` enum aliases. * The PRD explicitly prefers a Brief section first. A standalone route is a follow-up only if the section becomes cramped. * Static Brief rendering must continue to project before rendering, matching Phase 24 and Phase 27 privacy lessons. ### Potential Challenges * Verdict vocabulary mismatch: The session stub says "act / watch / research / skip" while shipped Session 08 uses `act_now / monitor / review / ignore`. Mitigation: use shipped enum values and labels as the code source of truth. * Brief crowding: Adding another section could push the Brief beyond a quick scanner. Mitigation: compact group rows, bounded topic counts, and no duplicate full Trend cards. * Legacy payloads: Older data may parse with default action fields. Mitigation: detect lack of meaningful verdict spread and show explicit unavailable copy where appropriate. ### Relevant Considerations * \[P02] **Extension payloads and labels stay bounded**: Decisions groups, reason summaries, and static export fields must stay capped and additive. * \[P24] **Browser-safe export and triage boundaries**: Static Brief export must keep local triage notes, private paths, and raw evidence out of exported output. * \[P27] **Trend Finder payload growth needs release checks**: New action grouping fields require payload, export, privacy, and Reference mode checks in closeout. * \[P01] **Extract pure functions, then test, then wire**: Build grouping helper coverage before rendering it in Brief and static export. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * A legacy/default action payload could look like a real recommendation unless unavailable state is explicit. * The static renderer could accidentally reach into raw payload fields and bypass the browser-safe projection boundary. * Workbench preset UI could preserve stale filters after report data changes unless state is reset or revalidated on row changes. *** ## 9. Testing Strategy ### Unit Tests * Decisions helper grouping, count totals, reason frequency ordering, verdict priority ordering, QA caution summaries, and unavailable state. * Workbench preset filter and sort behavior, including deterministic tie breakers. ### Integration Tests * Static Brief projection schema includes Decisions and clamps projected rows. * Static Brief renderer displays Decisions from projected data and handles empty/unavailable groups. * Brief view renders the Decisions section with accessible labels and no horizontal overflow-prone text. ### Manual Testing * Open the Brief route with fixture data containing Act now, Monitor, Review, and Ignore groups. * Resize to mobile width and verify group counts, reason chips, and topic rows stay readable without overlap. * Generate a static Brief export and verify Decisions appears without private paths, raw evidence dumps, prompts, or provider responses. ### Edge Cases * No topics. * Topics parsed from legacy payloads with default action fields. * All topics in one verdict group. * QA blocked/review caution present on top topics. * Long reason summaries and long topic names. * Workbench data changes while the verdict preset is active. *** ## 10. Dependencies ### External Libraries * None. Use existing TypeScript, React, Zod, Tailwind CSS, Vitest, and Testing Library dependencies only. ### Other Sessions * **Depends on**: `phase28-session08-action-verdicts-and-consistency-qa`, `phase24-session07-static-brief-export`, `phase24-session06-signal-workbench-local-triage`, and `phase27-session01-brief-movement-groups-and-calibration-metrics`. * **Depended by**: `phase28-session12-brief-qa-markdown-export-and-kpi-strip` and `phase28-session15-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/phase28-session09-action-queue-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.