LENS

PRD/PRD.md

LENS — Product Requirements Document

LENS stands for Leading Engagement & Narrative Synthesis. It is a social content intelligence platform that gives marketing teams an empirical, sourced understanding of how their own content is performing on social platforms — and how that performance compares to their competitors.

LENS is platform-agnostic by design. Version 1 starts with LinkedIn because that is where B2B content currently lives. Subsequent versions will add X and other platforms as the same analytical model extends naturally to them.

This document describes what LENS is, who it's for, what it does at the highest level, and what success looks like. It is the anchor document for the project. All other LENS documents (specs, designs, modules, data schemas, research notes) descend from this one.

1. Why LENS Exists

The marketing teams of B2B technology companies have an empirical blind spot. They publish content every week on social platforms — primarily LinkedIn — and they know roughly how that content performed in terms of impressions, reactions, and reposts. What they do not know, and cannot get from native platform analytics, is the deeper reality:

Who is actually engaging with their content — not as anonymous impression counts, but as named cohorts of real people, classified by persona, with trajectory over time.
Which content patterns are actually working — not for vanity metrics, but for the cohorts that matter to the business.
How their content performance compares to their competitors — at the level of cohorts, formats, narratives, and named engagers, not at the level of follower counts and reach.
Where their competitors are winning audiences they are losing — the asymmetries that reveal real competitive risk and real opportunity.

LENS exists to close this blind spot. It collects engagement data for the subject company and its competitors, classifies the engagers into personas, tracks how those cohorts shift over time, and surfaces the asymmetries that matter.

Once that empirical understanding exists, a natural downstream output follows: a small set of concrete content recommendations for the next week, traceable backward through the data to the specific cohorts, patterns, and signals that justify them.

The recommendations are valuable. But they are not why LENS exists. LENS exists to give marketing teams the insight that lets them — or the AI on their behalf — make those recommendations defensibly. Without the insight layer, the recommendations are just guesses. With it, they are the natural conclusion of an argument the data already made.

Why Software Is Required

Native platform analytics give marketers impressions and reach. Existing competitive intelligence platforms (Klue, Crayon) are built for sales battlecards, not editorial content planning, and they do not capture engager-level data. A script could pull engagement numbers but could not classify engagers into personas, track cohort trajectories, or detect cross-entity asymmetries that only emerge when multiple companies' data is analyzed side by side.

The thing LENS does that nothing else does: find the people, patterns, and gaps that exist in the space between the entities, not inside any single entity's data. That is the work software is required for.

2. Who Uses LENS

LENS has one product but two audiences. The same publication and the same workbench have to work for both.

Primary Users

VP / Director of Marketing — opens the weekly issue Monday morning, reads the cover and the editor's note in 90 seconds, scans the cohort comparison and the recommended content briefs, forwards to the team. They consume; they rarely investigate.
Head of Content / Content Marketing Manager — reads the full weekly issue, ships the recommended content briefs, occasionally opens Explore mode to investigate a specific question about performance or competitive position. They consume editorially and investigate selectively.
Social Media Lead / Content Creator — reads the briefs in the Closer of the weekly issue, copies the hooks, drafts the actual posts. Lives downstream of the publication and rarely needs to use Explore mode directly.

Secondary Users

CMO — receives the weekly issue forwarded from the VP of Marketing. Reads only the cover, the editor's note, and the closer. Never opens Explore mode. The publication has to read well at this depth alone.
Product Marketing / Competitive Intelligence Analyst — lives in Explore mode. Slices data across time windows and entities, pins findings for next week's issue, feeds the editorial pipeline from the bottom up.

The Editor (v1: Arijit)

The Editor — receives an AI-drafted issue every Sunday night, reviews and refines it in a dedicated review screen, approves and schedules it for Monday 8am publication. In v1 the editor is Arijit. In later versions the role transfers to a content lead at the licensed customer.

3. The Two Modes

LENS is built around exactly two modes, accessed through two tabs in the top bar of the application. Everything in LENS lives in one mode or the other.

Editorial Mode

Editorial mode is subject-centric. Everything about the subject company and nothing else. The reader of the weekly issue should be able to read it cover-to-cover and come away knowing everything that matters about the subject's own state — the content, the cohorts, the named engagers, the network movements in their own ecosystem, the recommended content briefs for the week — without ever having to think about a competitor.

The verb is consume. The reader is in receive mode. The publication arrives, they read it, they close it.

The cadence is weekly. A new issue is generated every Sunday night by the AI drafter, reviewed and approved by the editor Sunday night or early Monday, and published Monday at 8am.

Explore Mode

Explore mode is competitive. Subject vs. competitors. Where competitors are winning that the subject is not, which cohorts they are capturing, which content formats are outperforming, which narratives they are staking. The asymmetries are the entire surface.

The verb is investigate. The user is in active mode. They pick a question, they pick a time scope, they pick which competitors to compare against, they look at the answer, they drill in, they pin findings for next week's issue or export them.

The cadence is none — always on. Explore is a workbench, not a publication. The user controls the time scope (this week, last 30 days, last 3 months, last 6 months, last 12 months, or a custom date range).

The Bridge Between Modes

The two modes are explicitly connected by a bidirectional bridge:

Editorial → Explore — a reader of the weekly issue who wants to ask "how does this compare to competitors?" can click a contextual link in any section that opens Explore pre-filtered to the relevant view. The competitive context is preserved.
Explore → Editorial — an analyst investigating in Explore can pin any finding for inclusion in next week's issue. Pinned findings are prioritized by the AI drafter when it generates the next draft. The finding is automatically translated into subject-centric editorial language before it appears in the issue. The Weekly Issue never says "Constructor is beating us." It says "this is an opportunity for us."

This bridge is what makes LENS feel like one product instead of two.

4. The Four Product Principles

These principles govern how LENS works at every layer. Every document, every screen, every module must respect them.

Principle 1 — Sunday Sync

A scheduled background job runs every Sunday night at 23:00 UTC, before the weekly issue is drafted. It performs two tasks:

Verifies the executive roster for every monitored entity (subject and competitors) by querying each company's website (About, Leadership, Team pages) via web search and Perplexity. Output is a versioned JSON snapshot per week.
Detects drift by comparing this week's snapshot to last week's: new joiners, departures, promotions, title changes. Drift events are queued as story leads for the weekly issue and as data updates for the entity registry.

The Sunday Sync is the foundation of LENS's data integrity. Every other piece of analysis assumes the executive roster is current and verified. Without it, the rest of the product is built on stale assumptions.

The Sunday Sync does double duty: it is both data hygiene and an intelligence source. Executive transitions are themselves high-value competitive signals.

Principle 2 — Source Links Everywhere

Every claim LENS makes must link back to the public source it came from. No exceptions.

This applies to:

Every social post mentioned in any section (link to the post URL)
Every named engager (link to their public profile)
Every executive in the Sunday Sync (link to their public profile AND to the source page on the company website)
Every community thread cited (link to the thread)
Every partnership / event signal (link to the announcement)
Every competitor narrative claim (link to the supporting posts)

All linked sources are public. LENS analyzes only public posts, public profiles, public company websites, and public web content. There is no scraping of private accounts, no inferred personal data, no scraping behind login walls.

This principle is what makes LENS auditable end-to-end. A reader can pick any claim, click through to the source, and verify it themselves.

Principle 3 — Show The Work

Every recommended content brief in the weekly issue must show its work in four labeled boxes:

Cohort — which audience persona this brief targets, drawn from the cohort analysis in the issue.
Pattern — what we know about how this audience behaves, drawn from the patterns established earlier in the issue.
Signal — what happened this week that makes this brief actionable now (could be a subject-side event, a community thread, a competitive move surfaced from Explore mode, or a pinned finding from Explore).
Who To Reach — the named engagers from the cohort analysis who are the imagined readers of this specific brief.

A brief that cannot fill all four boxes cannot ship. The editor reviews each brief's confidence (1-4 markers based on the strength of each box) and may reject low-confidence briefs before publication.

Principle 4 — Audience Tracking

LENS tracks who is engaging with the subject company over time, broken into personas, with trajectory across multiple time windows (this week, last month, last 3 months, last 6 months).

A snapshot tells the reader who their audience is right now. A trajectory tells them how that audience is becoming what it is — which cohort is growing, which is contracting, which is stable. The trajectory is the insight that drives content targeting decisions.

The cohort analysis is foundational. Every content brief, every targeting recommendation, every "who to reach" list traces back to it. Without audience tracking, LENS would be guessing about who its recommendations are for.

5. Data Collection Policy

A product principle means nothing unless it is enforced at every layer of the system. This section defines exactly what LENS collects, what it does not collect, how it collects, how it handles data, and how it displays that data. These rules are enforced at three layers: the Source Catalog (gatekeeper), the ingestion modules (enforcement), and the rendering layer (last line of defense).

What LENS Collects

1. Company-owned pages on the open web - Company About / Leadership / Team / Executives pages on the company's own website - No authentication required - Treated as authoritative public statements by the company - Used by: Sunday Sync

2. Company posts on social platforms - Posts published by the company's own brand handle - Posts published by employees from their own personal accounts that publicly tag or reference the company - Only posts that are visible without a login (verified in incognito) OR that are surfaced via official platform APIs that respect each post's individual privacy setting - Used by: Post Ingestion

3. Engager identity from public engagement on public posts - Names, headlines, current employers of people who publicly liked, commented on, or reposted a public post - Only collected from posts that are themselves public - Only the identity fields the engager has chosen to make public on their own profile - Used by: Engager Capture

4. Public discussion on open community platforms - Hacker News threads (entirely public, no login required) - Reddit threads in public subreddits - GitHub repository activity (public repos only) - Public conference / event websites and agendas - Public press releases and partnership announcements - Used by: Community signals drill-downs in Explore mode

What LENS Does Not Collect

Private profiles, private posts, private accounts
Content behind login walls that is not surfaced via official platform APIs
Direct messages, private group content, paid newsletters
Email addresses, phone numbers, or contact details (even if technically public on a profile)
Inferred personal data — no enrichment from third-party data brokers, no identity resolution beyond what the person has chosen to publish themselves
Sentiment analysis or psychological profiling of named individuals
Geographic or demographic data not explicitly published by the person themselves

How LENS Collects

Through official platform APIs wherever they exist (LinkedIn Marketing Developer Platform, X API, Reddit API, GitHub API, HN Firebase API)
Through licensed third-party providers (Apify actors, Perplexity, etc.) only when those providers themselves operate within the source platform's terms of service AND only when the provider is the responsible party for compliance with that platform's terms
By reading public web pages on the open web (company websites, press releases, conference pages) using standard HTTP requests and respecting robots.txt
Never by circumventing authentication, rate limits, or technical access controls

How LENS Handles the Data

Every record is stored with its source URL and the timestamp of collection
Every record is stored with the collection method (which provider, which API, which scrape)
Every record is stored with the licensing basis (platform API ToS, web public, licensed provider)
Any record without a verifiable source URL is rejected at ingestion and never enters the database
Engagers can be removed from LENS on request — there is a documented manual process (v1: email request, manual removal) and a delete pipeline

How LENS Displays the Data

Every claim links to the original public source (the Source Links Everywhere principle from Section 4)
Every named individual links to their own public profile so the reader can verify the identity is real and the person has chosen to make that profile public
The Colophon of every weekly issue includes a standing statement: "LENS analyzes only public content from public profiles. All sources linked. All collection performed via official APIs or licensed providers operating within platform terms."

Three Enforcement Layers

The policy is not decorative. It is enforced in code at three layers:

Layer	Where	What It Enforces
Gatekeeper	Source-Catalog	Every external data source must be documented with platform, access method, legal basis, and collected fields. Sources without a clear legal basis are not added.
Ingestion	Module-02-Post-Ingestion, Module-03-Engager-Capture	Every record must include source URL, collection timestamp, collection method, and licensing basis. Records without a verifiable source URL are rejected. A deny list is honored for engagers who have requested removal. Every collection event is logged for audit.
Rendering	Module-08-Reader-Frontend	No claim renders without a source URL. No engager renders without a profile link. Missing source links cause the claim to be omitted, not displayed without attribution.

6. Editorial Mode — At a Glance

The Weekly Issue is an editorial publication, not a dashboard. It follows a fixed arc of nine screens / sections, every issue, in the same order. Detailed specifications live in Editorial-Mode-Spec.

1.  COVER         The week's claim — two short parallel sentences
2.  OPENER        Editor's note in first person, 80–150 words
3.  § 1           The week's thesis (one claim, one visual)
4.  § 2           What performed (top three posts, ranked)
5.  § 3           Who's engaging with us (cohort comparison
                  across four time windows)
6.  § 4           Who was watching (five named engagers)
7.  § 5           Network movements (subject's own ecosystem —
                  exec moves, partnerships, events)
8.  CLOSER        Three Content Briefs ready to ship
9.  COLOPHON      Issue metadata, source coverage, sign-off

Every section follows a fixed template. The reader develops muscle memory across issues. A CMO who reads only the cover, the opener, and the closer gets the whole week in 90 seconds. A content lead who reads everything gets the full picture in 6–10 minutes.

Editorial mode contains nothing about competitors. Competitive analysis lives entirely in Explore mode.

7. Explore Mode — At a Glance

Explore mode is a workbench organized around exactly four top-level lenses. Each lens answers one competitive question that cannot be answered by looking at one entity in isolation.

The Four Top-Level Lenses

1. Cohort Gap Which audience personas are over-indexed or under-indexed for the subject versus the competitive set, and how is the gap shifting over time? The headline lens. The view that justifies the existence of the entire product.

2. Switcher Signal Which named engagers interact with both the subject and a competitor, and which way are they leaning? The most defensible capability — engager-level overlap data is not available in any other competitive intelligence tool.

3. Content Gap What format or content type is winning for a competitor that the subject is not winning at? Surfaces format-level asymmetries with the actual winning posts linked.

4. Narrative Gap What topic is a competitor staking that the subject has gone silent on? Surfaces topic-level asymmetries via a topic ownership grid.

Drill-Down Layers Inside Each Lens

Eight supporting analyses live as nested drill-down layers inside the relevant top-level lens, not as their own top-level destinations. This keeps Explore mode focused on the four questions that matter while still giving analysts the depth they need when a gap demands investigation.

The full nesting:

COHORT GAP
  ↳ Audience composition per entity
  ↳ Executive voices speaking to each cohort
  ↳ Network movements across the field

SWITCHER SIGNAL
  ↳ Network movements (joiners, leavers across the field)

CONTENT GAP
  ↳ Content performance per entity
  ↳ Community signals per format (HN, Reddit, GitHub)

NARRATIVE GAP
  ↳ Executive voices championing each topic
  ↳ Event footprint per topic
  ↳ Partnership moves signaling category direction

When the user finds something interesting in any of the drill-down layers, they can pin it for inclusion in next week's issue. Detailed specifications live in Explore-Mode-Spec.

8. Scope — In and Out for v1

In Scope for v1

Two modes (Editorial + Explore) with the bidirectional bridge
Editorial mode: 9 screens (cover, opener, 5 sections, closer, colophon)
Explore mode: landing screen plus 4 top-level lens screens, each with their nested drill-down layers
Editor review screen (Sunday night workflow, single-editor model)
Archive of past issues
Settings screen for monitored entity configuration
Sunday Sync with drift detection
Source Links Everywhere applied to every renderable claim
Show The Work applied to every content brief
Audience Tracking with four time windows (this week, last month, last 3 months, last 6 months)
All four asymmetry lenses with their nested drill-down layers
Pin-to-next-issue bridge from Explore to Editorial
LinkedIn as the only data platform
Single-tenant: Algolia is the subject company
Data Collection Policy enforced at all three layers

Deferred to v1.5 / v2

X (Twitter) as a second data platform
Multi-tenancy and licensing to other subject companies
Hiring signals as an asymmetry dimension
Pricing & packaging signals as an asymmetry dimension
Voice Gap as a separate asymmetry lens (folded into Narrative Gap for v1)
Standalone entity dossier views
Multi-editor / collaborative review workflow
Integration with PRISM for account-level deep dives
Mobile / responsive layouts (desktop only for v1)
Slack and email delivery channels (export to PDF only for v1)
Automated deny list / self-service removal request flow (v1 uses manual email process)

Explicitly Out of Scope

Any analysis of private platform data, private profiles, or scraped content behind authentication walls
Sales battlecards or sales enablement features (LENS is editorial, not sales)
Real-time alerts or push notifications (LENS publishes on a weekly cadence, by design)
Dashboards with arbitrary user-defined charts (Explore mode is opinionated; the four lenses are fixed)
Third-party data broker enrichment or identity resolution beyond publicly self-published data
Sentiment analysis or psychological profiling of named individuals

9. Success Criteria

LENS v1 is successful if:

The editor can review and approve a weekly issue in under 30 minutes every Sunday night, including refining the cover claim, the editor's note, and any content briefs that need adjustment.
A CMO reading only the cover, the editor's note, and the closer gets a complete and accurate picture of the week in 90 seconds or less.
A content marketer can ship at least one of the recommended content briefs as drafted, without rewriting, in any given week.
An analyst using Explore mode can identify a real cohort gap or switcher signal that was not visible in the editorial issue, and pin it for inclusion in next week's issue.
Every claim in every published issue links to a verifiable public source. A skeptic can pick any claim and trace it backward to the underlying data within two clicks.
The Sunday Sync runs successfully every week for at least four consecutive weeks without manual intervention, and detects at least one real executive transition during that period that becomes a story lead.
No record in the database lacks a source URL, collection timestamp, or licensing basis. An audit of the database at any point returns zero orphaned records.

10. Open Questions

The following decisions are not yet locked and may block later work if not resolved before the relevant module is built. Each question links to the document where it will be answered.

Which Apify actor (or alternative) will be used for LinkedIn post ingestion? Decision needed before Module-02-Post-Ingestion can be built. → Source-Catalog
What is the persona classification heuristic for engagers? Five personas are named (Ecommerce Builder, AI/ML Practitioner, GTM Leader, CS Leader, AI Founder) but the actual classification logic — based on job title, company, headline, profile content — is not yet specified. → Persona-Classification
Is engager identity capture for competitor posts (not just subject posts) legally cleared for v1? This affects whether Switcher Signal can ship at full capability or in a reduced "subject-side only" form. → Module-03-Engager-Capture
What is the database choice and hosting target? Postgres is assumed but not yet specified. Hosting (local laptop in v1, per existing project constraints) is assumed but the migration path to a hosted environment for v2 needs to be designed in. → Database-Schema
What is the AI prompt structure for the Issue Drafter module? The drafter must produce content that follows the templated arc, the editorial voice rules, and the Show The Work principle. The actual prompt structure is not yet designed. → Module-06-Issue-Drafter
What is the deny list process for engager removal requests? v1 needs at minimum a documented manual process. The delete pipeline must cascade through all tables that reference the engager. → Database-Schema

11. Document Map

The full LENS documentation set:

README
FolderStructure