> 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-session01-editorial-quick-wins/spec.md). # Session Specification **Session ID**: `phase29-session01-editorial-quick-wins` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-19 *** ## 1. Session Overview This session starts Phase 29 by raising the editorial quality floor for Trend Finder copy and tightening existing noise scoring against engagement-farming creator content. It adds an anti-AI-trope voice guard to the analyst prompt path, mirrors the same discipline in deterministic fallback copy, and extends the analyst validator so banned stock phrases fail the same way invented IDs, URLs, dates, source names, and metrics already fail. The second half of the session folds the reviewed tutorial-hype and engagement-farming pattern set into the existing `topic-quality.ts` noise path. The goal is not a new browser field; hype detection feeds existing `contentPatternPenalty`, `topicNoiseRisk`, and `topicNoiseDownrank` behavior so downstream surfaces continue to consume the same bounded data contract. The session also documents broader social reach through X/TikTok/Instagram/Bluesky as a deliberate non-goal under the current terms, API, and PII posture. That keeps Session 01 aligned with Phase 29's boundary intent: borrow editorial sharpness from TrendingAI without borrowing source risk. *** ## 2. Objectives 1. Add an anti-AI-trope voice guard to Trend Finder analyst instructions without weakening evidence-grounding rules. 2. Reject reviewed banned phrases in analyst output through the existing validation and fallback path. 3. Downrank engagement-farming topic titles using existing topic-quality noise scoring. 4. Document the social-reach coverage gap as a deliberate non-goal with no implied collector approval. *** ## 3. Prerequisites ### Required Sessions * [x] `phase28-session15-documentation-validation-and-release` - Phase 28 closeout certified the Trend Finder source, payload, documentation, and release validation baseline. ### Required Tools/Knowledge * Bun and Vitest test workflow through `bun run test`. * Existing analyst validation path in `scripts/lib/ai-runtime/trend-analyst.ts`. * Existing topic visibility and noise path in `scripts/lib/ai-runtime/topic-quality.ts`. * Current source compliance language in `docs/extensions/trend-finder-sources.md`. ### Environment Requirements * Work from repo root with Bun dependencies installed. * Keep generated private runtime data, provider responses, prompts, and source rows out of committed artifacts. * Preserve ASCII-only output and Unix LF line endings for all session files. *** ## 4. Scope ### In Scope (MVP) * Trend Finder analyst receives an ANTI-AI-TROPE prompt block covering forbidden openers, hedges, hype terms, rhetorical reflexes, em-dash-as-soft-pause, and mechanism verbs over vague verbs - implemented in existing prompt constants. * Trend Finder deterministic fallback copy follows the same voice discipline - implemented through existing fallback/template helpers rather than a new runtime contract. * Trend Finder analyst validation rejects reviewed banned phrases - implemented as an additive validator issue that triggers the current retry/fallback behavior. * Trend Finder topic scoring recognizes reviewed creator-hype patterns - implemented near `contentPatternRegexes` and fed into existing topic noise downrank behavior. * Trend Finder documentation records X/TikTok/Instagram/Bluesky as a known social-reach coverage gap and deliberate non-goal - implemented in the existing sources manual. ### Out of Scope (Deferred) * New browser-visible hype field - Reason: Session 01 intentionally reuses existing topic noise scoring and browser payload fields. * New source or collector for X/TikTok/Instagram/Bluesky - Reason: Phase 29 defines broader social reach as a non-goal under current terms, API, and PII posture. * Reception polarity or attention pattern fields - Reason: Session 02 and Session 03 own those derived fields. *** ## 5. Technical Approach ### Architecture The implementation stays inside existing Trend Finder extension boundaries. Analyst prompt and validation changes live in `scripts/lib/ai-runtime/trend-analyst.ts`, where schema parsing, invented-metadata checks, retry, and fallback reporting already exist. Topic noise changes live in `scripts/lib/ai-runtime/topic-quality.ts`, where `contentPatternRegexes`, `contentPatternPenalty`, and `calculateNoiseDownrank` already combine into existing visibility fields. No schema or browser payload field should be added. Tests should prove the new behavior through current outputs: analyst fallback issues for banned phrases and stronger topic-quality downrank for engagement-farming titles. ### Design Patterns * Additive validation: Extend the current validator with a new issue code and normalized issue output so retry/fallback behavior remains unchanged. * Deterministic fallback first: Keep useful fallback copy available without depending on an AI runtime. * Existing scoring path: Feed hype detection into `contentPatternPenalty` and `topicNoiseDownrank` rather than creating a new presentation field. * Documentation as boundary: Record unapproved social sources as non-goals without adding collector language. ### Technology Stack * TypeScript under Bun. * Zod-backed analyst output parsing. * Vitest unit tests under existing `__tests__` locations. * Markdown docs under `docs/extensions/`. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---- | --------------------------------------------------------------------------------------------------- | ---------- | | None | No new application files expected; this is an additive change to existing runtime, tests, and docs. | 0 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- | | `scripts/lib/ai-runtime/trend-analyst.ts` | Add anti-trope instructions, banned-phrase validation, and fallback-copy discipline. | \~90 | | `scripts/lib/ai-runtime/topic-quality.ts` | Add reviewed engagement-farming pattern set and wire it into existing topic noise scoring. | \~55 | | `scripts/lib/ai-runtime/__tests__/trend-analyst.test.ts` | Cover prompt block, banned phrase rejection, accepted copy, and fallback behavior. | \~90 | | `scripts/lib/ai-runtime/__tests__/topic-quality.test.ts` | Cover engagement-farm downrank and useful tutorial non-regression. | \~70 | | `docs/extensions/trend-finder-sources.md` | Add broader social-reach non-goal paragraph with current boundary wording. | \~25 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Analyst prompts include the anti-AI-trope voice guard while preserving evidence-grounding requirements. * [ ] Analyst output containing a reviewed banned phrase fails validation and enters the current retry/fallback path. * [ ] Legitimate grounded copy that does not contain banned phrases passes validation. * [ ] Engagement-farming topic titles increase topic noise downrank through existing visibility fields. * [ ] Source docs describe X/TikTok/Instagram/Bluesky as a deliberate non-goal with no implied source approval. ### Testing Requirements * [ ] Unit tests written and passing for analyst validation and topic-quality scoring. * [ ] Focused tests run for `trend-analyst.test.ts` and `topic-quality.test.ts`. * [ ] Manual diff review confirms no browser payload field or source activation was introduced. ### Non-Functional Requirements * [ ] No prompt, provider response, token, raw source row, private path, or unapproved social-source content enters browser-safe output. * [ ] Existing deterministic fallback behavior remains available when AI runtime output is rejected. * [ ] Existing 1 MB extension payload boundary is unchanged because no new browser field is added. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * Keep pattern names and issue codes descriptive, but avoid adding global `findtrend` identifiers. * Prefer reviewed, specific phrase and regex patterns over broad sentiment or hype words that would create false positives. * Keep docs focused on current behavior. The social-reach paragraph must say these platforms are not collected, not that they are planned or partially supported. * Do not mutate schema or browser payload fields unless implementation uncovers an unavoidable contract need; current PRD scope expects no new field. ### Potential Challenges * Banned-phrase false positives: Mitigate with a reviewed phrase list, accepted-copy fixtures, and scope validation to analyst-generated public copy fields. * Useful tutorials downranked as hype: Mitigate with tests that preserve legitimate, specific tutorial wording while downranking CTA/listicle engagement farming. * Documentation implying source approval: Mitigate with explicit non-goal wording and references to compliance-first source activation. ### Relevant Considerations * \[P02] **Extension payloads and labels stay bounded**: This session should not add a browser-visible field; all behavior feeds existing bounded outputs. * \[P27] **Deterministic fallback before AI enrichment**: Voice discipline must apply to fallback copy before optional analyst output is accepted. * \[P28] **Direct public source scope is narrow**: X/TikTok/Instagram/Bluesky stay uncollected unless a future source-specific compliance phase approves them. * \[P00] **Do not document planned features as implemented**: The sources manual must state the social-reach gap as not collected and not approved. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Analyst validation rejects legitimate grounded copy because banned patterns are too broad. * Topic noise scoring suppresses useful specific tutorials instead of only engagement-farming formats. * Source documentation is misread as approval to collect broader social data. *** ## 9. Testing Strategy ### Unit Tests * Add analyst tests that assert the prompt contains the anti-trope block and banned phrases cause fallback-required validation. * Add analyst tests that accepted grounded copy with mechanism verbs passes validation. * Add topic-quality tests that engagement-farming titles produce higher `topicNoiseDownrank` and high-noise risk. * Add topic-quality tests that useful, specific tutorial wording is not automatically suppressed. ### Integration Tests * No browser e2e is required because this session adds no new browser-visible field. * Existing focused unit tests are the main integration proof because the changed runtime helpers feed current report generation paths. ### Manual Testing * Review diffs for accidental schema, source declaration, or browser payload changes. * Review `docs/extensions/trend-finder-sources.md` to confirm the social-reach paragraph is a non-goal, not a roadmap promise. ### Edge Cases * Analyst output with banned phrase inside `summary`, `whyNow`, `creatorAngle`, `plainExplainer`, `suggestedTitle`, hooks, questions, run notes, demand briefs, theme labels, or outlier ideas. * Copy that names a real product or mechanism and contains no banned phrase. * Titles with CTAs such as "save this thread", "DM me", "top 0.1%", six-plus item listicles, hashtag closers, and "only X you need". * Multi-source, high-quality topic with one tutorial-like evidence title that should not be fully suppressed. *** ## 10. Dependencies ### External Libraries * None new. ### Internal Modules * `scripts/lib/ai-runtime/trend-analyst.ts` * `scripts/lib/ai-runtime/topic-quality.ts` * `docs/extensions/trend-finder-sources.md` ### Other Sessions * **Depends on**: Phase 28 completed. * **Depended by**: `phase29-session02-attention-pattern-and-polarity-grid` uses Session 01 title heuristics and editorial baseline. *** ## 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-session01-editorial-quick-wins/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.