> 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/phase29-session05-per-evidence-rationale/spec.md).

# Session Specification

**Session ID**: `phase29-session05-per-evidence-rationale` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-19

***

## 1. Session Overview

This session adds a bounded "why this item" explanation to each evidence link that supports a Trend Finder topic. Phase 29 has already shipped editorial cleanup, attention/polarity presentation, aggregate-only reception, and the corroboration gate. Session 05 now tightens the evidence layer itself: if a topic cites evidence, the system should be able to explain why that specific item supports the topic without inventing facts.

The implementation must support both paths that produce topics. When the AI analyst is available, it can emit one short rationale per cited evidence item. The validator must reject unknown evidence IDs, fabricated metadata, and rationales that cannot be grounded in the cited evidence. When the AI runtime is unavailable, a deterministic fallback must produce safe rationales from existing relevance score, evidence quality, matched entity or source-local signal, source role, and topic identity.

Weak analyst-only evidence should not be carried into topic rendering simply to make a topic look better. If a cited item cannot be justified, the topic projection should omit that item from browser-visible evidence links while preserving the raw normalized row in the generated evidence collection. Live Evidence to verify surfaces and the static Brief should show concise rationale copy without leaking raw provider output, private paths, prompts, or unreviewed source data.

***

## 2. Objectives

1. Add an optional, schema-defaulted per-evidence rationale projection for topic evidence links.
2. Extend analyst output and validation so every AI rationale is tied to an existing cited evidence ID and grounded in the cited row.
3. Add a deterministic fallback rationale builder that works without the AI runtime.
4. Omit weak or unjustified evidence from topic rendering without deleting raw normalized evidence rows.
5. Surface rationales in live Evidence to verify and static Brief evidence rows with payload, privacy, and accessibility safety.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase28-session15-documentation-validation-and-release` - Certifies Phase 28 validator, browser payload, and static Brief boundaries.
* [x] `phase29-session01-editorial-quick-wins` - Updates the shared analyst validator path that this session extends.
* [x] `phase29-session04-corroboration-gate` - Confirms the latest additive derived-field and evidence-safety patterns are green.

### Required Tools/Knowledge

* Bun 1.3.14 workflow through `bun run test`.
* Existing analyst output validation in `scripts/lib/ai-runtime/trend-analyst.ts`.
* Existing topic projection and collector order in `scripts/extensions/trend-finder/collector.ts`.
* Existing evidence link projection in `src/extensions/trend-finder/view-model.ts` and `src/extensions/trend-finder/components/evidence-links.tsx`.
* Existing static Brief projection, renderer escaping, and QA scan utilities.

### Environment Requirements

* Project dependencies installed with Bun.
* `src/data/live-data.example.json` available for fixture and payload validation.
* No new source, media, database, hosted storage, or third-party transfer approval is required because this session reuses already-collected public evidence.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder can publish a bounded per-evidence rationale - Add a short optional rationale for each topic evidence link, keyed to existing evidence IDs.
* AI analyst output can justify cited items - Extend analyst output, prompt example, and schema validation for one rationale per cited evidence item.
* Validator can reject fabricated rationale output - Reject unknown evidence IDs, invented URLs, dates, source names, metrics, and unsupported metadata in rationale text.
* Deterministic fallback can explain evidence without AI - Build a rationale from topic identity, relevance score, source role, matched entity, source-local signal, and quality components where available.
* Topic projection can omit weak links - Drop unjustified evidence from topic evidence links while preserving raw normalized rows in `data.evidence`.
* Operators can inspect rationales - Render concise rationale copy in live Evidence to verify and static Brief evidence rows.
* Release checks can prove safety - Add tests for validation, fallback, weak-link omission, schema defaults, rendering, payload size, and privacy boundaries.

### Out of Scope (Deferred)

* Cross-topic substrate narratives - Reason: Session 06 reuses this citation-validation discipline for run-level narratives.
* Deleting or mutating raw normalized source rows - Reason: This session only changes topic projection and display.
* New source collection, social reach, comments, transcripts, or media handling - Reason: These remain compliance-gated or out of scope for Phase 29.
* Long-form citation summaries or multi-paragraph evidence analysis - Reason: The MVP is one bounded line per evidence link.
* Changing topic score formulas only because a rationale exists - Reason: The requirement is evidence projection honesty, not a new ranking signal.

***

## 5. Technical Approach

### Architecture

Create a small evidence-rationale helper under `scripts/lib/ai-runtime/`. It should own the bounded rationale contract, deterministic fallback builder, basic grounding helpers, and weak-link classification. The helper should accept safe topic and evidence inputs, produce short display-safe rationale text, and return explicit omission reasons when an item cannot be justified.

Extend `trend-analyst.ts` so analyst output can include per-topic evidence rationales keyed by cited evidence ID. Validation should run after the existing schema parse and no-invented-metadata walk. The validator must require rationale IDs to be a subset of the topic's cited evidence IDs, cap length, reject unknown evidence IDs, and reuse grounding checks so rationales cannot introduce URLs, dates, source names, metrics, or claims that do not exist in the cited row.

Wire rationale projection after scored topics exist and before browser evidence links are assigned. AI rationales should win when valid; otherwise deterministic fallback rationales should fill safe gaps. If neither path can justify an analyst-only evidence link, remove that evidence ID from the topic projection and record a safe warning or omission reason. Do not remove the evidence from the raw normalized evidence array.

The browser schema should use additive defaults so old payloads parse safely. `joinEvidenceLinks()` should project rationale labels onto existing evidence link view models, and `EvidenceLinks` should render the copy within the current card layout. Static Brief export should include the same bounded text in its evidence row schema, and the renderer should escape it through existing helpers.

### Design Patterns

* Additive schema evolution: Legacy payloads parse with empty rationale maps and no rendered rationale copy.
* Deterministic fallback before AI enrichment: Topic evidence links remain explainable when the AI runtime is absent.
* Boundary-nearest validation: Analyst rationale output is rejected before it reaches scoring, browser payload, or static export.
* Projection over mutation: Weak evidence is omitted from topic links while raw normalized rows remain available for diagnostics and future runs.
* Bounded browser projection: Publish short display copy and safe omission labels, not raw prompts, provider responses, private paths, or raw source dumps.

### Technology Stack

* TypeScript and Zod for runtime contracts and schema defaults.
* Bun and Vitest for script/runtime tests.
* React 19 view-model and component tests with happy-dom.
* Existing static Brief export, renderer, QA, and payload-size utilities.

***

## 6. Deliverables

### Files to Create

| File                                                          | Purpose                                                                                                   | Est. Lines |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/ai-runtime/evidence-rationale.ts`                | Bounded rationale types, deterministic fallback builder, grounding helpers, and weak-link classification. | \~220      |
| `scripts/lib/ai-runtime/__tests__/evidence-rationale.test.ts` | Unit coverage for fallback rationales, weak-link omission, bounded text, and evidence grounding cases.    | \~220      |

### Files to Modify

| File                                                                      | Changes                                                                                                       | Est. Lines |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/ai-runtime/trend-analyst.ts`                                 | Extend analyst prompt/output schema and validation for per-evidence rationales.                               | \~160      |
| `scripts/extensions/trend-finder/collector.ts`                            | Merge AI/fallback rationales into topic projection and omit unjustified weak links without deleting raw rows. | \~120      |
| `scripts/extensions/trend-finder/topics.ts`                               | Add fallback rationale assignment for deterministic frequency and similarity fallback topics.                 | \~70       |
| `src/extensions/trend-finder/schema.ts`                                   | Add rationale constants, topic field defaults, evidence-link rationale schema, and legacy-safe parsing.       | \~120      |
| `src/extensions/trend-finder/view-model.ts`                               | Project rationale text, tone, and accessibility labels onto evidence link view models.                        | \~90       |
| `src/extensions/trend-finder/components/evidence-links.tsx`               | Render concise rationale copy in existing evidence cards with stable layout and accessible text.              | \~50       |
| `scripts/extensions/trend-finder/static-brief-export.ts`                  | Add rationale to static Brief evidence-row schema and projection with bounded text only.                      | \~50       |
| `scripts/extensions/trend-finder/static-brief-renderer.ts`                | Render escaped rationale copy in static Brief evidence cards.                                                 | \~35       |
| `scripts/extensions/trend-finder/measure-payload-size.ts`                 | Ensure rationale fields remain visible in payload-size reporting and budget checks.                           | \~20       |
| `src/extensions/trend-finder/fixtures.ts`                                 | Add fixture evidence/topic examples for AI rationale, fallback rationale, and omitted weak evidence.          | \~70       |
| `scripts/lib/ai-runtime/__tests__/trend-analyst.test.ts`                  | Cover accepted grounded rationale, fabricated rationale rejection, and unknown evidence IDs.                  | \~110      |
| `scripts/extensions/trend-finder/__tests__/collector.test.ts`             | Cover topic projection omission while raw normalized evidence remains present.                                | \~90       |
| `src/lib/__tests__/trend-finder-schema.test.ts`                           | Cover legacy defaults and invalid rationale payload fallback behavior.                                        | \~70       |
| `src/extensions/trend-finder/__tests__/view-model.test.ts`                | Cover evidence-link rationale projection, labels, and missing rationale behavior.                             | \~70       |
| `src/extensions/trend-finder/components/__tests__/trend-card.test.tsx`    | Cover rendered Evidence to verify rationale copy and accessible card text.                                    | \~60       |
| `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts`   | Cover static projection and private/raw field exclusion.                                                      | \~70       |
| `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Cover escaped rationale rendering and no raw/private leakage.                                                 | \~50       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `evidenceRationale` or equivalent topic evidence projection defaults safely for legacy payloads.
* [ ] A valid AI rationale is accepted only when it references an existing evidence ID cited by that topic.
* [ ] A fabricated rationale that introduces unsupported URL, source, date, metric, or source-local claim is rejected by the validator.
* [ ] A deterministic fallback rationale exists when the AI runtime is absent.
* [ ] Weak analyst-only evidence is omitted from topic rendering without deleting the raw normalized source row.
* [ ] Live Evidence to verify and static Brief evidence cards render concise rationale copy.

### Testing Requirements

* [ ] Unit tests written and passing for rationale validation, fallback generation, and weak-link omission.
* [ ] Schema/view-model/component tests cover legacy defaults, labels, accessibility text, and missing rationale behavior.
* [ ] Static Brief export/renderer tests cover escaped rationale output and privacy cleanliness.
* [ ] Payload-size check confirms the extension remains under the 1 MB boundary.
* [ ] Focused test commands recorded in implementation notes during the implement step.

### Non-Functional Requirements

* [ ] Browser payload stays under the 1 MB extension budget.
* [ ] Static Brief and live browser payloads do not expose raw source dumps, private paths, prompts, provider responses, raw model output, comments, transcripts, or credentials.
* [ ] No new source, collector, media boundary, database, hosted storage path, dependency, or third-party transfer is introduced.
* [ ] Rationale copy is bounded, deterministic where needed, and stable enough for repeated operator review.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] New enum or schema branches use explicit fallback behavior.

***

## 8. Implementation Notes

### Key Considerations

* The raw evidence collection remains the audit trail. This session only narrows topic evidence projection when a link cannot be justified.
* The fallback builder should prefer concrete cues already present on evidence rows: relevance score, source role, source-local entity, competitor match, quality components, and topic name.
* Rationale text must stay short enough for dense dashboard cards and static Brief evidence rows.
* The validator should reject AI output before it reaches scoring or display; do not rely on view rendering to hide unsafe rationale text.
* Static Brief export should receive projected safe rationale text, not raw analyst output.

### Potential Challenges

* Over-strict validation could reject useful rationales. Mitigation: validate IDs and fabricated metadata strongly, then let deterministic fallback supply safe wording.
* Weak-link omission could make topics look under-supported. Mitigation: preserve raw rows and add tests proving only the topic projection changes.
* Payload pressure could grow if every evidence link gets text. Mitigation: cap rationale length and static Brief evidence count through existing limits.
* UI density could suffer. Mitigation: render one compact rationale line within existing evidence cards and keep layout dimensions stable.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: Rationale text must be short, defaultable, and measured against the 1 MB payload budget.
* \[P24] **Browser-safe export and triage boundaries**: Static Brief must exclude raw evidence dumps, private paths, local triage notes, prompts, provider responses, and credentials.
* \[P27] **Deterministic fallback before AI enrichment**: Fallback rationale generation must work before and without optional analyst output.
* \[P28] **Direct public source scope is narrow**: This session adds no source and does not widen deferred social or media candidates.
* \[P28] **Trend Finder release validation is bundled**: Payload, privacy, docs/reference checks, and scoped formatting evidence should be recorded during implementation and closeout.
* \[P00] **Do not document planned features as implemented**: Any docs changed during implementation must describe shipped rationale behavior only after code lands.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* AI rationale text introduces an unsupported claim and still reaches browser-visible evidence cards.
* Weak evidence is deleted from raw normalized rows instead of only being omitted from topic projection.
* Legacy payloads without rationale fields break Evidence to verify or static Brief rendering.

***

## 9. Testing Strategy

### Unit Tests

* Add evidence-rationale helper tests for fallback text from relevance score, source role, matched entity, source-local signal, and topic identity.
* Add analyst validator tests for accepted grounded rationales, unknown evidence IDs, fabricated source/metric/date claims, and missing rationale fallback behavior.
* Add collector/topic projection tests proving unjustified weak evidence is omitted from topic links while raw normalized evidence remains present.

### Integration Tests

* Add schema tests for legacy payload defaults and invalid rationale payload fallback.
* Add view-model/component tests for rationale labels, accessible text, missing-rationale behavior, and long-text truncation.
* Add static Brief export/renderer tests for escaped rationale markup and no private path/raw output leakage.
* Add payload-size validation to confirm rationale fields stay within the extension budget.

### Manual Testing

* Generate or load fixture Trend Finder data and inspect `/extensions/trend-finder/brief` Evidence to verify cards.
* Export a static Brief and inspect the Evidence to verify section for concise rationale copy.
* Confirm an omitted weak evidence row remains in raw generated evidence data but no longer appears as a topic evidence link.

### Edge Cases

* Legacy payload has no rationale fields.
* Analyst cites a rationale for evidence not in the topic's `evidenceIds`.
* Analyst rationale mentions a source, URL, date, or metric absent from the cited evidence.
* Evidence has no source-local signal or matched entity.
* Evidence URL is missing or non-public.
* All evidence for a topic is weak or unjustified.

***

## 10. Dependencies

### External Libraries

* None. This session should not add dependencies.

### Other Sessions

* **Depends on**: Phase 28 validator and evidence-link projection paths; `phase29-session01-editorial-quick-wins` for the current analyst validator baseline.
* **Depended by**: `phase29-session06-cross-topic-substrate-narratives`, `phase29-session08-required-derived-field-closeout-gate`, and `phase29-session13-static-brief-archival-and-richness`.

***

## 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/phase29-session05-per-evidence-rationale/spec.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.