> 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-session02-attention-pattern-and-polarity-grid/spec.md).

# Session Specification

**Session ID**: `phase29-session02-attention-pattern-and-polarity-grid` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-19

***

## 1. Session Overview

This session adds the Phase 29 attention-pattern axis to ranked Trend Finder topics. The field answers "what kind of attention is this" without changing the existing action-priority contract: `actionRecommendation` still decides what to do next, while `attentionPattern` labels the observed attention shape as adoption, creator hype, announcement, discourse, or unavailable.

The implementation follows the established derived-field path. Runtime derivation starts from existing source-role shares and the Session 01 title heuristics, the Zod schema adds a backwards-compatible default, and browser/static projections expose only bounded labels. No new source, comment body, prompt, provider response, cache path, private path, or raw source row is introduced.

The user-facing deliverable is a compact polarity/attention grid in the Trends header and static Brief. The grid combines movement, action verdict, and `attentionPattern`, while reserving an explicit reception column for Session 03. This gives operators a fast run-level read now and leaves the aggregate-only reception work cleanly scoped to the next session.

***

## 2. Objectives

1. Add deterministic `attentionPattern` derivation from role shares and reviewed title heuristics.
2. Publish `attentionPattern` through schema defaults, fixtures, browser payloads, and payload-size reporting.
3. Project a compact polarity/attention grid for live Trends and static Brief surfaces.
4. Prove legacy parsing, deterministic derivation, browser safety, static export safety, and visible grid behavior with focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase29-session01-editorial-quick-wins` - Provides reviewed engagement-hype title heuristics and the editorial baseline this session reuses.
* [x] `phase28-session15-documentation-validation-and-release` - Provides the prior payload, source, static Brief, and release validation baseline.

### Required Tools/Knowledge

* Bun and Vitest workflow through `bun run test`.
* Existing source-role and camp derivation in `scripts/lib/ai-runtime/source-breakdown.ts`.
* Additive Zod defaults in `src/extensions/trend-finder/schema.ts`.
* Trend Finder projection helpers in `src/extensions/trend-finder/view-model.ts`.
* Static Brief projection and rendering in `scripts/extensions/trend-finder/static-brief-export.ts` and `static-brief-renderer.ts`.
* Playwright e2e guards for Trend Finder browser and static Brief surfaces.

### Environment Requirements

* Work from repo root with dependencies installed.
* Keep generated private runtime data, provider output, prompts, comment bodies, source dumps, and local cache paths out of committed artifacts.
* Preserve ASCII-only output and Unix LF line endings for all session files.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder ranked topics get `attentionPattern` with states `adoption`, `creator-hype`, `announcement`, `discourse`, and `unavailable` - implemented as an additive derived field with deterministic fallback.
* Trend Finder derivation uses existing role shares and Session 01 title/content heuristics - implemented near `deriveTopicSourceBreakdowns` or a focused helper called from it.
* Trend Finder schema and fixtures parse old payloads safely - implemented with enum constants, `DEFAULT_*` literal, and `.default()`/`.catch()` behavior.
* Trend Finder live view model exposes bounded grid rows - implemented as projection helpers over movement, action verdict, attention pattern, and a reserved reception placeholder.
* Trend Finder Trends header renders a compact polarity/attention grid - implemented with explicit loading, empty, error, and offline-safe surface behavior inherited from the view.
* Trend Finder static Brief exports and renders the same grid - implemented through static report projection, schema, renderer, and privacy scan coverage.
* Trend Finder docs describe the field, derivation limits, and the Session 03 reception placeholder - implemented in scoring and UI-surface docs.

### Out of Scope (Deferred)

* `receptionSignal` derivation or filled reception polarity - Reason: Session 03 owns aggregate-only reception and the `contested-reception` flag.
* New source, social platform, podcast, or comment-body collection - Reason: Phase 29 keeps source expansion compliance-gated and this session uses existing aggregate metadata only.
* Score caps or action-verdict demotion based on `attentionPattern` - Reason: The session defines attention vocabulary, not action priority or risk scoring.
* Hosted storage, database schema, or snapshot model changes - Reason: This is an additive browser/static payload field inside the current local JSON contract.

***

## 5. Technical Approach

### Architecture

The runtime field is derived where topic source-role context is already assembled. `source-breakdown.ts` builds `roleShares`, `builderSignalShare`, and `camp`; this session adds a deterministic attention helper that reads role shares plus topic/evidence titles available in the current payload path. The helper must return `unavailable` when evidence is absent, roles are unknown, or title heuristics are insufficient.

The schema adds `TREND_ATTENTION_PATTERNS`, a `TrendAttentionPattern` type, `DEFAULT_TREND_ATTENTION_PATTERN`, and an `attentionPattern` field on `TrendTopicSchema`. The field defaults to `unavailable` for legacy payloads and remains a short enum string for payload-budget discipline.

The view layer projects the enum into labels, tones, per-topic grid rows, and run-level counts. The same projection should feed the Trends header component and static Brief report projection so UI copy, ordering, and fallback behavior remain consistent. The reception column should render as "Reserved" or "Session 03" rather than inventing sentiment.

### Design Patterns

* Additive schema evolution: Legacy payloads parse to the explicit `unavailable` state.
* Deterministic fallback first: No AI runtime is needed for a valid `attentionPattern`.
* Projection before rendering: Browser and static surfaces consume sanitized display models, not raw runtime rows.
* Bounded labels: Enums, labels, counts, and short descriptions only; no raw source body or private provenance.
* Reusable UI: Keep the grid component small, accessible, and usable in dense dashboard layout without nested cards.

### Technology Stack

* TypeScript under Bun.
* Zod schema defaults and catches.
* React 19, Tailwind CSS 4, local Trend Finder component patterns.
* Vitest for runtime, schema/projection, component, and static renderer tests.
* Playwright for visible Trends and static Brief guards.

***

## 6. Deliverables

### Files to Create

| File                                                                                | Purpose                                                                                | Est. Lines |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/trend-finder/components/polarity-attention-grid.tsx`                | Reusable compact grid for movement, action, attention, and reserved reception columns. | \~130      |
| `src/extensions/trend-finder/components/__tests__/polarity-attention-grid.test.tsx` | Component accessibility, empty-state, and long-label coverage for the grid.            | \~90       |

### Files to Modify

| File                                                                      | Changes                                                                                      | Est. Lines |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/ai-runtime/source-breakdown.ts`                              | Derive `attentionPattern` from role shares and title heuristics with deterministic ordering. | \~90       |
| `scripts/lib/ai-runtime/__tests__/source-breakdown.test.ts`               | Cover all attention states, unavailable fallback, and role/title precedence.                 | \~120      |
| `src/extensions/trend-finder/schema.ts`                                   | Add enum/type/default/schema field and legacy parsing fallback.                              | \~45       |
| `src/extensions/trend-finder/fixtures.ts`                                 | Add representative fixture attention states for browser, static Brief, and e2e data.         | \~30       |
| `src/extensions/trend-finder/view-model.ts`                               | Add labels, tones, grid row projection, and run-level grid summary helpers.                  | \~130      |
| `src/extensions/trend-finder/__tests__/view-model.test.ts`                | Cover grid projection, legacy default, labels, ordering, and reserved reception column.      | \~110      |
| `src/extensions/trend-finder/views/trends-view.tsx`                       | Render the grid in the Trends header with explicit empty/error/offline-safe behavior.        | \~60       |
| `scripts/extensions/trend-finder/static-brief-export.ts`                  | Add grid fields to `StaticBriefReport`, schema, projection, and privacy QA path.             | \~90       |
| `scripts/extensions/trend-finder/static-brief-renderer.ts`                | Render the static Brief grid with escaped labels and bounded rows.                           | \~70       |
| `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts`   | Prove projected report includes sanitized grid rows and no raw payload leakage.              | \~60       |
| `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Prove rendered HTML includes grid landmarks, escaped text, and no private strings.           | \~55       |
| `scripts/extensions/trend-finder/measure-payload-size.ts`                 | Include `attentionPattern` in payload pressure reporting and threshold context.              | \~25       |
| `docs/extensions/trend-finder-scoring.md`                                 | Document derivation, states, limits, and distinction from action verdicts.                   | \~45       |
| `docs/extensions/trend-finder-ui-surfaces.md`                             | Document the Trends/static Brief grid and reserved reception column.                         | \~40       |
| `tests/e2e/trend-finder.spec.ts`                                          | Assert the live Trends grid renders with fixture data and remains mobile safe.               | \~35       |
| `tests/e2e/trend-finder-static-brief.spec.ts`                             | Assert exported static Brief renders the grid and preserves private-string guards.           | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `attentionPattern` publishes on ranked topics with an explicit `unavailable` default for legacy data.
* [ ] Derivation produces `adoption`, `creator-hype`, `announcement`, `discourse`, and `unavailable` from deterministic role-share and title inputs.
* [ ] The field remains distinct from `actionRecommendation`; it labels observed attention shape and does not decide priority.
* [ ] Trends header renders a compact grid for movement, action verdict, attention pattern, and reserved reception.
* [ ] Static Brief exports and renders the same grid without raw source rows, prompts, private paths, tokens, or comment bodies.
* [ ] Payload size measurement remains under the shared 1 MB boundary.

### Testing Requirements

* [ ] Unit tests written and passing for source derivation and legacy schema parsing.
* [ ] View-model and component tests cover label/tone projection, empty states, ordering, and accessibility labels.
* [ ] Static Brief export and renderer tests cover report schema, escaped rendering, and privacy scan behavior.
* [ ] Playwright e2e guards cover the live Trends grid and exported static Brief grid on desktop/mobile.

### Non-Functional Requirements

* [ ] No new source, comment-body, transcript, provider-response, prompt, token, raw row, cache path, or private provenance boundary is introduced.
* [ ] Grid rows are bounded, deterministic, keyboard/screen-reader accessible, and resilient to long topic names.
* [ ] All additive payload fields have explicit unavailable/fallback states.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.

***

## 8. Implementation Notes

### Key Considerations

* Derivation should use role shares first, then reviewed title/content heuristics, with deterministic tie-breaking and a conservative `unavailable` fallback.
* Keep `creator-hype` scoped to the reviewed Session 01 engagement-farming signals and creator-role dominance; do not make generic excitement a catch-all.
* Keep the grid compact. It belongs in the dashboard header as dense operational context, not as a new marketing section.
* The reception column must be visibly reserved for Session 03 and must not imply sentiment analysis exists yet.
* Update fixtures intentionally so e2e assertions prove multiple states, not only the default.

### Potential Challenges

* Ambiguous role-share mixes: Mitigate with a deterministic precedence table and tests that document ties.
* False-positive creator-hype labels: Mitigate by reusing reviewed Session 01 markers and adding useful tutorial non-regression coverage.
* Payload drift: Mitigate with enum-only topic data, static projection privacy tests, and `measure-payload-size.ts`.
* UI crowding on mobile: Mitigate with stable grid dimensions, wrapping labels, and Playwright overflow checks.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: `attentionPattern` is a short enum with an explicit unavailable state and bounded display labels.
* \[P24] **Browser-safe export and triage boundaries**: Static Brief must use projected rows only and must not include browser-local triage notes, raw evidence, private paths, or raw source payloads.
* \[P27] **Deterministic fallback before AI enrichment**: This field is deterministic and valid without AI runtime output.
* \[P28] **Direct public source scope is narrow**: This session adds no source and does not imply social, podcast, or comment-body approval.
* \[P00] **Stack conventions**: Keep Bun, React, TanStack Start, Tailwind, and Cloudflare Worker compatibility intact.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Legacy payloads without `attentionPattern` fail parsing or render blank grid cells.
* Live or static grid labels imply reception sentiment exists before Session 03.
* Mobile Trends header becomes crowded or horizontally scrolls.

***

## 9. Testing Strategy

### Unit Tests

* Add source-breakdown tests for each attention state, role-share precedence, title-heuristic fallback, and no-evidence unavailable behavior.
* Add schema/view-model tests proving legacy payloads default to `unavailable`, labels/tone mapping is stable, and the reception column is reserved.
* Add component tests for grid accessibility, empty state, and long topic names.
* Add static Brief tests for report projection, renderer escaping, privacy scan, and no raw payload leakage.

### Integration Tests

* Run focused Vitest suites for source breakdown, view model, grid component, static Brief export, and static Brief renderer.
* Run `bun run trend-finder:measure-payload-size -- src/data/live-data.example.json --threshold-kb=1024` or the existing package alias if available.

### Manual Testing

* Review generated fixtures and HTML to confirm attention labels are visible, bounded, and distinct from action verdicts.
* Review docs to confirm Session 03 reception remains deferred and no new source collection is implied.

### Edge Cases

* Topics with no evidence IDs or only missing evidence rows.
* Role-share ties across developer, creator, launch, news, discussion, research, and unknown roles.
* Titles with Session 01 engagement-farming markers but strong developer/research adoption evidence.
* Legacy payloads missing `actionRecommendation`, `movementStatus`, or `attentionPattern`.
* Very long topic names in grid rows on mobile and in static Brief HTML.

***

## 10. Dependencies

### External Libraries

* None new.

### Internal Modules

* `scripts/lib/ai-runtime/source-breakdown.ts`
* `src/extensions/trend-finder/schema.ts`
* `src/extensions/trend-finder/view-model.ts`
* `src/extensions/trend-finder/views/trends-view.tsx`
* `scripts/extensions/trend-finder/static-brief-export.ts`
* `scripts/extensions/trend-finder/static-brief-renderer.ts`

### Other Sessions

* **Depends on**: `phase29-session01-editorial-quick-wins`.
* **Depended by**: `phase29-session03-reception-signal-aggregate-only`, `phase29-session08-required-derived-field-closeout-gate`, and later static Brief richness work.

***

## 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-session02-attention-pattern-and-polarity-grid/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.