> 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/phases/phase_28/session_08_action_verdicts_and_consistency_qa.md).

# Session 08: Per-Topic Action Verdicts And Consistency QA

**Session ID**: `phase28-session08-action-verdicts-and-consistency-qa` **Status**: Complete **Completed**: 2026-06-14 **Estimated Tasks**: 24 **Estimated Duration**: 2-4 hours

***

## Objective

Add a deterministic per-topic action verdict (`act_now | monitor | review | ignore`) composed from existing fields and the Tier 2 gates, with an explainable reasons array, plus an evidence-to-action consistency QA gate that demotes the verdict and labels overstated creator angles rather than rewriting AI output.

***

## Source Mapping (from the Trends-Finderz improvement map, items 4.1 and 4.3)

### Per-topic action recommendation (item 4.1)

* **Trends-finderz:** every trend gets a decision -- `act_now | monitor | review | ignore` ("Act on this", "Watch this", "Research-only, validate first", "Avoid this") -- composed from lifecycle fit, evidence fit, watchlist drift, score bands (`strong | qualified | borderline | weak`), urgency, and hard caps from the visibility gate (a `research_only` topic can never score above 47; reliable evidence requires >= 2 sources with >= 3 mentions).
  * `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/trends/action-priority.ts`
* **Trend Finder today:** actionability exists only at the **evidence-row** level (source-local lift bands, `scripts/extensions/trend-finder/source-local-signals.ts`); no topic-level "what should I do about this" verdict exists anywhere in the payload.
* **Improvement:** deterministic per-topic recommendation from existing fields (score, movement, hidden-gem flag, source diversity, evidence strength) plus the gates from Sessions 04-07 (noise gate, visibility band, aging, saturation, research-only). Carry a reasons array (same pattern as watchlist reason codes in `docs/extensions/trend-finder-scoring.md`) so every verdict is explainable.
* **Implement in:** new `scripts/lib/ai-runtime/action-priority.ts` called from `scripts/extensions/trend-finder/collector.ts`; schema enum + reasons in `src/extensions/trend-finder/schema.ts`; verdict chip on `src/extensions/trend-finder/components/trend-card.tsx`.

### Evidence-to-action consistency QA (item 4.3)

* **Trends-finderz:** six deterministic cross-checks verify the product never overstates its evidence: product verdict vs validation state, aging vs action ("Stale evidence cannot support an Act recommendation"), research caveat vs action, source confidence vs action, quality gate vs action, and saturation vs action -- producing `clean | review | blocked`, contradiction strings, and a recommended fix; `blocked` downgrades the action wording.
  * `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/product/evidence-action-consistency.ts`
* **Trend Finder today:** creator angles, hooks, and watchlist reasons are validated for *invented content* but not for *overstatement* -- an AI-composed "jump on this now" angle can sit next to a topic whose entire evidence set is one low-tier source from nine days ago.
* **Improvement:** run the consistency checks as a post-analysis gate over each topic's (angle, verdict, evidence-state) triple. On `blocked`, demote the verdict and label the creator angle with a caution chip rather than rewriting AI output. This extends the existing validation philosophy: validators catch fabrication; this catches miscalibration.
* **Implement in:** same module as item 4.1 or `scripts/lib/ai-runtime/action-consistency.ts`; consumed in `scripts/extensions/trend-finder/collector.ts`; caution label in `src/extensions/trend-finder/components/creator-lens-panel.tsx` / `trend-card.tsx`.

***

## Scope

### In Scope (MVP)

* `action-priority.ts` deterministic per-topic verdict from existing fields plus the Tier 2 gates, with hard caps (research-only ceiling, reliable-evidence floor)
* Verdict enum + reasons array in the schema (additive default) and a verdict chip
* Consistency QA gate (`clean | review | blocked`) over the (angle, verdict, evidence-state) triple with contradiction strings
* `blocked` demotes the verdict and labels the creator angle with a caution chip (no AI rewrite)
* Tests: verdict composition, hard caps, each consistency cross-check, blocked demotion, legacy parsing

### Out of Scope

* The Action Queue surface that groups by verdict (Session 09)
* Rewriting analyst output (gate demotes/labels only)
* New AI calls (both items are deterministic over existing fields)

***

## Prerequisites

* [x] Session 04 completed (visibility band / noise gate inputs)
* [x] Session 05 completed (aging and refined saturation inputs)
* [x] Session 07 completed (research-only flag input)

***

## Deliverables

1. `action-priority.ts` deterministic verdict with reasons array and hard caps
2. Verdict enum/reasons schema fields and a card chip
3. Consistency QA gate with contradiction strings and recommended fixes
4. Blocked-state verdict demotion and creator-angle caution chip
5. Tests for verdict logic, caps, consistency checks, and legacy parsing

***

## Success Criteria

* [x] Every topic carries a deterministic verdict with an explainable reasons array
* [x] Hard caps hold: a research-only topic cannot read as `act_now`; reliable evidence requires the minimum source/mention thresholds
* [x] A "jump on this now" angle over stale/thin evidence is flagged `blocked`, the verdict demoted, and the angle labeled with caution -- AI text intact
* [x] No new AI or source calls are introduced
* [x] Legacy payloads parse; existing tests pass


---

# 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/phases/phase_28/session_08_action_verdicts_and_consistency_qa.md?ask=<question>&goal=<endgoal>
```

`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.