> 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-session08-action-verdicts-and-consistency-qa/spec.md). # Session Specification **Session ID**: `phase28-session08-action-verdicts-and-consistency-qa` **Phase**: 28 - Trend Finder Trends-Finderz Adoption **Status**: Not Started **Created**: 2026-06-14 *** ## 1. Session Overview This session starts Phase 28 Tier 3 by turning the derived scoring, visibility, aging, lifecycle, saturation, and research-only signals into a deterministic per-topic action verdict. Trend Finder currently explains what is moving and why it is scored a certain way, but it does not give each topic a bounded "what should I do with this" recommendation. The session adds a script-side action layer that produces `act_now`, `monitor`, `review`, or `ignore` with bounded reason codes, score bands, urgency, and calibration notes. It must consume only existing topic fields and the Session 04-07 gates. It must not add AI calls, source calls, dependencies, storage, or new collection behavior. The session also adds an evidence-to-action consistency QA gate. The gate checks whether a verdict and creator angle overstate the evidence state. When evidence contradicts action wording, the gate demotes the verdict and labels the creator angle with a caution chip instead of rewriting AI-authored text. *** ## 2. Objectives 1. Add a deterministic per-topic action verdict with score, band, urgency, and explainable bounded reasons. 2. Enforce hard caps from existing Tier 2 gates, including research-only, visibility, reliable-evidence, stale evidence, quality/noise, and saturation constraints. 3. Add an evidence-to-action consistency QA gate with clean, review, and blocked states plus bounded contradiction strings and recommended fixes. 4. Surface verdict and QA status through legacy-safe schema defaults, Trend card chips, creator-angle caution labeling, fixtures, and tests. *** ## 3. Prerequisites ### Required Sessions * [x] `phase28-session04-topic-noise-gate-and-visibility-bands` - provides topic quality gates, visibility bands, and reason codes consumed by the action caps. * [x] `phase28-session05-signal-aging-half-lives-and-saturation-refinement` - provides signal aging and refined saturation inputs for action timing. * [x] `phase28-session06-lifecycle-multiplier-and-named-contributions` - provides lifecycle and named score-adjustment context for action reasons. * [x] `phase28-session07-research-only-calibration-and-cache-retention` - provides the `research-only` risk flag input and current cache hygiene baseline. ### 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, scoring, collector, view-model, Trend card, fixture, and documentation patterns. * Trends-Finderz reference files: `EXAMPLES/trends-finderz/lib/trends/action-priority.ts` and `EXAMPLES/trends-finderz/lib/product/evidence-action-consistency.ts`. ### 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, credential flows, or write-capable action queue behavior. *** ## 4. Scope ### In Scope (MVP) * Trend Finder can derive one topic-level action verdict from existing score, creator potential, source diversity, evidence count, visibility band, topic quality, signal aging, lifecycle, saturation, hidden-gem, movement, and research-only risk inputs. * Trend Finder can publish bounded action fields with additive Zod defaults: verdict, score, score band, urgency, reasons, warnings, next-step copy, and calibration metadata. * Trend Finder can enforce hard caps: research-only topics cannot become `act_now`; suppressed or rejected topics become `ignore`; `act_now` requires reliable evidence with at least two sources and at least three evidence mentions; stale, high-noise, or highly saturated topics are demoted. * Trend Finder can run six deterministic consistency checks over verdict, creator-angle wording, visibility, aging, research-only, source confidence, quality/noise, and saturation state. * Trend Finder can demote blocked verdicts and label the creator angle with a caution chip while leaving AI output text unchanged. * Trend Finder can show action verdict and QA/caution status on Trend cards with compact, accessible chips and stable wrapping. * Tests cover verdict composition, hard caps, reason ordering, QA checks, blocked demotion, legacy parsing, UI labels, fixture scenarios, and collector wiring. ### Out of Scope (Deferred) * Grouping verdicts into a Decisions Brief or Action Queue surface - *Reason: Session 09 owns the action queue presentation.* * Watchlist pin baselines, notes, tags, and verdict triage writes - *Reason: Session 10 owns browser-local pin metadata.* * Search palette or embeddings - *Reason: Session 11 owns command palette and deterministic embeddings.* * Static Brief export decisions section - *Reason: Session 09 owns export projection after verdicts exist.* * Rewriting analyst/creator-angle output - *Reason: this session demotes and labels only.* * New AI calls, source collection, compliance-gated adapters, runtime dependencies, or persistence backends - *Reason: the action layer is deterministic over existing local payload fields.* *** ## 5. Technical Approach ### Architecture Add pure script-side action helpers under `scripts/lib/ai-runtime/`. The action priority helper should define the verdict enum, score bands, urgency levels, bounded reason codes, warnings, calibration metadata, and a default legacy-safe recommendation. Input parsing must be schema validated and permissive enough to handle older topic payloads through defaults. The action score should be calibrated from current Trend Finder fields rather than copied from Trends-Finderz constants. It should weigh current score, creator potential, evidence strength, source diversity, hidden-gem score, visibility score, lifecycle stage, signal aging, and movement, then apply caps for research-only, suppressed/rejected visibility, weak reliable evidence, stale evidence, high noise, saturated topics, and blocked QA. Add a separate consistency helper for cross-checks. Checks should cover verdict vs visibility, aging vs action, research-only vs action, source confidence vs action, quality/noise vs action, saturation vs action, and overstatement in creator-angle or hook text. Results should produce `clean`, `review`, or `blocked`, a bounded score, contradiction strings, and a recommended fix. Wire the helpers after scored topics have all Session 04-07 derived fields available. The collector should attach action fields to each topic, apply blocked-state demotion, and emit trace summaries with verdict counts, QA counts, and warning counts only. No private paths, raw source dumps, or AI prompt text should enter action trace output. Extend `src/extensions/trend-finder/schema.ts` with additive defaults for action recommendation and consistency QA. Extend `view-model.ts` to provide labels, tones, aria text, reason summaries, and creator-angle caution presentation. Trend card rendering should place the verdict chip near existing derived signal chips and the caution chip next to the angle pack when QA is not clean. ### Design Patterns * Pure function, then tests, then wire: implement action scoring and QA as pure helpers before collector integration. * Zod additive defaults: old generated payloads, fixtures, snapshots, and tests parse without a migration. * Browser-safe projection: expose bounded enums, counts, labels, reasons, and sanitized fixes only. * Deterministic fallback before AI enrichment: no new analyst calls or dynamic output generation. * Existing component patterns: compact chips, 8px-or-less radii where possible, accessible labels, focus support for informational chips, and no layout shift. ### Technology Stack * Bun 1.3.14 for scripts and test execution. * TypeScript for application and script code. * Zod for payload parsing and legacy defaults. * React 19 and Tailwind CSS 4 for existing Trend card surfaces. * Vitest for script, schema, view-model, component, and collector coverage. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------- | | `scripts/lib/ai-runtime/action-priority.ts` | Deterministic action verdict scoring, caps, reasons, urgency, and defaults | \~260 | | `scripts/lib/ai-runtime/action-consistency.ts` | Evidence-to-action QA checks, blocked/review status, contradiction strings, and demotion metadata | \~240 | | `scripts/lib/ai-runtime/__tests__/action-priority.test.ts` | Verdict, score-band, hard-cap, reason-order, and default coverage | \~220 | | `scripts/lib/ai-runtime/__tests__/action-consistency.test.ts` | QA check, contradiction, creator-angle overstatement, and demotion coverage | \~220 | | `.spec_system/specs/phase28-session08-action-verdicts-and-consistency-qa/implementation-notes.md` | Record constants, calibration rationale, validation commands, and residual risks | \~80 | ### Files to Modify | File | Changes | Est. Lines | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/trend-finder/schema.ts` | Add action verdict, score band, urgency, reason, QA, and default schemas | \~170 | | `scripts/extensions/trend-finder/collector.ts` | Attach action recommendations after scoring, apply QA demotion, and emit sanitized trace counts | \~140 | | `src/extensions/trend-finder/view-model.ts` | Add verdict, reason, QA, and caution-chip labels, tones, summaries, and aria text | \~180 | | `src/extensions/trend-finder/components/trend-card.tsx` | Render verdict chip and creator-angle caution chip with stable wrapping and accessible labels | \~90 | | `src/extensions/trend-finder/fixtures.ts` | Add representative `act_now`, `monitor`, `review`, `ignore`, and blocked-QA topics | \~90 | | `src/lib/__tests__/trend-finder-schema.test.ts` | Cover legacy defaults and action field parsing | \~90 | | `src/extensions/trend-finder/__tests__/view-model.test.ts` | Cover action labels, tones, summaries, and caution projection | \~100 | | `src/extensions/trend-finder/components/__tests__/trend-card.test.tsx` | Cover chip rendering, caution labels, and empty/default states | \~90 | | `scripts/extensions/trend-finder/__tests__/collector.test.ts` | Cover collector action wiring, demotion, trace summaries, and no raw text leakage | \~130 | | `docs/extensions/trend-finder-scoring.md` | Document shipped verdict semantics, hard caps, QA gate, and no-rewrite behavior | \~70 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Every parsed topic has a deterministic action recommendation with a verdict, score, score band, urgency, reasons, warnings, and next-step text. * [ ] Research-only, suppressed, rejected, stale, high-noise, weak-evidence, and high-saturation cases are capped or demoted deterministically. * [ ] `act_now` is impossible unless reliable evidence thresholds are met. * [ ] Consistency QA produces `clean`, `review`, or `blocked` with bounded contradictions and a recommended fix. * [ ] `blocked` QA demotes the visible action verdict and labels the creator angle with caution without rewriting AI text. * [ ] Trend cards show action and QA/caution chips with accessible labels and stable mobile/desktop wrapping. ### Testing Requirements * [ ] Unit tests written and passing for action priority helper behavior. * [ ] Unit tests written and passing for action consistency helper behavior. * [ ] Schema, view-model, component, fixture, and collector tests written and passing. * [ ] Manual Trend card check completed for clean, review, blocked, and legacy topics. ### Non-Functional Requirements * [ ] No new AI calls, source calls, third-party dependencies, credential paths, hosted storage, or write-capable surfaces are introduced. * [ ] Action arrays and contradiction strings are bounded to protect the shared 1 MB extension payload limit. * [ ] Trace output reports only verdict counts, QA counts, and sanitized warning counts. * [ ] Legacy payloads parse with action defaults and no migration step. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run test -- scripts/lib/ai-runtime/__tests__/action-priority.test.ts` passes. * [ ] `bun run test -- scripts/lib/ai-runtime/__tests__/action-consistency.test.ts` passes. * [ ] Focused schema, view-model, component, and collector tests pass. *** ## 8. Implementation Notes ### Key Considerations * Do not copy Trends-Finderz numeric constants directly. Use the reference to identify behavior classes, then calibrate against this repo's fields and existing Phase 28 score gates. * Keep action fields additive and bounded. The action layer must not expand unbounded reason arrays or leak raw source details. * The consistency gate labels or demotes; it must not mutate AI-authored creator angle text. * `research-only` appears both as a visibility band and a risk flag in current code. Treat either as a caution input for action caps. ### Potential Challenges * Mapping Trends-Finderz lifecycle and validation names to current Trend Finder fields: use current `TrendTopic` schema fields as source of truth and record any non-portable reference concepts in implementation notes. * Avoiding verdict churn from aggressive caps: keep reasons visible and constants conservative; tests should prove borderline topics land in `monitor` or `review`, not `act_now`. * Creator-angle overstatement detection can be brittle: use a small bounded phrase list for action language, and only label caution when evidence state contradicts the wording. * Collector trace output can accidentally expose too much context: trace counts and enum summaries only. ### Relevant Considerations * \[P02] **Extension payloads and labels stay bounded**: action reasons, warnings, contradictions, and fixes must have explicit length and count limits. * \[P05] **Script-only runtime boundary**: action math and QA stay under `scripts/lib/` or `scripts/extensions/`; browser code reads validated payload fields only. * \[P24] **Browser-safe export and triage boundaries**: the action layer should not expose raw evidence dumps, private paths, local notes, or source internals in browser-visible copy. * \[P27] **Trend Finder payload growth needs release checks**: new action arrays increase payload size and should be bounded before Session 09 export work. * \[P27] **Deterministic fallback before AI enrichment**: this session ships deterministic verdicts and QA only. * \[P01] **Extract pure functions, then test, then wire**: action priority and consistency QA should be tested before collector/UI integration. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * An `act_now` recommendation could overstate weak, stale, or research-only evidence. * Legacy or malformed payloads could break Trend Finder route rendering if action defaults are not robust. * Creator-angle caution could be visually hidden or misread if the chip is not placed close to the copied angle text. *** ## 9. Testing Strategy ### Unit Tests * Action priority tests cover score bands, hard caps, reliable-evidence floors, reason and warning limits, research-only demotion, suppressed/rejected ignore behavior, stale/high-noise/high-saturation caps, and defaults. * Action consistency tests cover each deterministic cross-check, blocked vs review thresholds, creator-angle overstatement labeling, contradiction bounding, and demotion recommendations. * Schema tests cover omitted action fields, malformed arrays, bounded strings, invalid enums, and legacy payload parsing. * View-model tests cover labels, tones, aria text, reason summaries, QA status, and caution projection. ### Integration Tests * Collector tests cover attaching action fields to scored topics, applying blocked-state demotion, preserving original AI text, and emitting sanitized verdict/QA trace counts. * Component tests cover Trend card verdict chips, creator-angle caution chips, empty/default action states, and accessible labels. ### Manual Testing * Open Trend Finder with fixture data and verify clean, review, blocked, and legacy topics render without layout overlap. * Verify copied creator angle text remains unchanged when a caution chip is present. * Confirm no new action queue or Brief Decisions section appears in this session. ### Edge Cases * Missing `signalAging`, `lifecycle`, `topicVisibilityBand`, or `riskFlags`. * `research-only` present as a visibility band but not a risk flag, and vice versa. * One source with three mentions, two sources with two mentions, and two sources with three mentions. * Suppressed/rejected topics with otherwise high scores. * Stale evidence with high creator potential. * Empty creator angle, overstatement wording in hooks only, and blocked QA with no angle text. *** ## 10. Dependencies ### External Libraries * None. Use existing TypeScript, Zod, React, Tailwind CSS 4, and Vitest setup. ### Other Sessions * **Depends on**: `phase28-session04-topic-noise-gate-and-visibility-bands`, `phase28-session05-signal-aging-half-lives-and-saturation-refinement`, `phase28-session06-lifecycle-multiplier-and-named-contributions`, and `phase28-session07-research-only-calibration-and-cache-retention`. * **Depended by**: `phase28-session09-action-queue-surface`, `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-session08-action-verdicts-and-consistency-qa/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.