> 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_29/session_05_per_evidence_rationale.md).

# Session 05: Per-Evidence Rationale

**Session ID**: `phase29-session05-per-evidence-rationale` **Status**: Complete **Completed**: 2026-06-20 **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Add bounded per-evidence justification and let weakly-linked evidence drop from topic rendering instead of carrying fabricated relevance. Maps comparison item 1.7, "why this item" per-evidence justification.

***

## Scope

### In Scope (MVP)

* Add an optional `evidenceRationale` per topic evidence link or equivalent topic projection.
* AI path: analyst emits one short rationale per cited item; the validator must verify each rationale references actual cited evidence and introduces no unsupported claims.
* Deterministic fallback: build rationale from relevance score, matched entity, source-local signal, and topic identity where available.
* Render in "Evidence to verify". If the analyst cannot justify an item, omit it from the topic evidence projection without deleting the raw normalized row.
* Add schema defaults and confirm payload safety.

### Out of Scope

* Cross-topic narratives (Session 06 reuses this citation-validation discipline).
* Deleting or mutating raw normalized source rows.

***

## Prerequisites

* [x] Phase 28 analyst validator and evidence-link projection paths green.

***

## Deliverables

1. Optional `evidenceRationale` field with validator-checked AI path.
2. Deterministic fallback rationale builder.
3. Weak-evidence omission from topic projection that preserves the raw row.
4. Unit tests for fabricated-rationale rejection and fallback presence.

***

## Success Criteria

* [x] Fabricated-rationale output is rejected by the validator.
* [x] Fallback rationale exists when the AI runtime is absent.
* [x] Weak analyst-only evidence is omitted from topic rendering without deleting the raw normalized source row.
* [x] Payload budget and privacy scans remain green.

***

## Key Files

* `scripts/extensions/trend-finder/topics.ts`
* `scripts/lib/ai-runtime/trend-analyst.ts`
* `scripts/extensions/trend-finder/normalize.ts`
* `scripts/extensions/trend-finder/sources/source-quality.ts`
* `src/extensions/trend-finder/schema.ts`
* `src/extensions/trend-finder/components/evidence-links.tsx`
* `src/extensions/trend-finder/view-model.ts`
* `scripts/extensions/trend-finder/static-brief-renderer.ts`

***

## Comparison Notes (folded from comparison plan)

**Effort:** Medium. **Boundary risk:** Low.

**1.7 Per-evidence "why this item" justification.** TrendingAI's `cited_items_why` map requires one honest line per cited item, and items the model cannot justify are dropped from rendering. Trend Finder links evidence but does not explain why each item supports a topic. Add optional `evidenceRationale` per topic evidence link, validator-bounded and backed by a deterministic fallback using relevance score, matched entity, source-local signal, and topic identity.

**TrendingAI source pointers.** `prompts/feature-sentiment.md` (`cited_items_why`).


---

# 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_29/session_05_per_evidence_rationale.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.