AI Prompts

Recommended build tool, guardrails, sequence, requirements, and handoff prompt.

Recommended AI Build Tool

Cursor

Why

### Cursor - **Why this tool:** Full-stack Next.js/Supabase project in an existing GitHub repo; complex backend logic (LLM orchestration, data processing, RLS policies) benefits from Cursor's codebase-aware context and agentic editing. - **Best fit for this project:** Build the data upload → LLM analysis pipeline → signals dashboard as a cohesive vertical slice, with Cursor handling schema design, API routes, and prompt engineering in one session. - **Expected starting cost:** Free tier first; $20/month Pro plan once iteration starts (likely within week 1). - **Watch out:** Cursor's LLM suggestions can hallucinate Supabase RLS policy syntax — always verify policies against Supabase docs and test with two different org_ids to confirm tenant isolation. - **Handoff instruction:** Clone your repo, open it in Cursor, and paste the Next Prompt into the Cursor chat with "Apply to codebase" mode.

Next Prompt

01 / 04

first-version-prompt.txt
```text
You are helping me build the MVP for Signal To Roadmap.

Product type: AI-first (primary), B2B SaaS (secondary)
Recommended first version: Functional software MVP with CSV/text upload

MVP goal: Validate whether PMs will use LLM-generated theme clusters from their
uploaded customer data to support real roadmap prioritization decisions.

Definition of done: A PM can upload a CSV or paste text (200+ customer interaction
records), receive ranked pain-point clusters with anonymized quotes and
recommendations, and indicate whether the output is useful.

Target user: Senior Product Manager at a mid-market B2B SaaS company (500–2K
employees) who owns roadmap prioritization and currently relies on anecdotal
customer feedback.

Core user flows:
- Upload customer data (CSV or pasted text, any source labeling)
- LLM analysis pipeline (GPT-4o clustering with two-tier model architecture)
- Signals dashboard (top 10 pain-point themes ranked by frequency + recency)
- Theme detail view (summary, 5 anonymized quotes, recommendation)
- Export recommendation as Markdown (copy-to-clipboard)
- Sample/demo mode with pre-loaded synthetic dataset
- Auth via Supabase magic link

Tech stack:
- Frontend: Next.js (App Router) + Tailwind + shadcn/ui
- Backend: Next.js API routes
- Database: Supabase (PostgreSQL) with Row-Level Security
- Auth: Supabase Auth (magic link)
- AI: OpenAI API (GPT-4o for clustering, GPT-4o-mini for filtering)
- File Storage: Supabase Storage
- Analytics: PostHog (free tier)
- Deployment: Vercel + Supabase hosted

Recommended AI build tool: Cursor — full-stack Next.js/Supabase codebase with
complex LLM orchestration and RLS policies benefits from Cursor's codebase-aware
context.

Build only this first chunk:
Step 1 — Standalone LLM prompt prototype: A Python or Node script that reads a
sample CSV of customer support tickets, sends batches to the OpenAI API with a
clustering prompt, and outputs structured JSON with: theme labels (2–6 words),
summary paragraphs (50–100 words per cluster), frequency counts, and up to 5
anonymized quotes per cluster with source attribution. The script should include
a two-tier architecture: GPT-4o-mini for filtering irrelevant records before
sending the rest to GPT-4o for clustering. Output a quality rubric that a PM can
use to rate: accuracy, specificity, actionability, and "would I use this?" on a
1–5 scale. Include a sample input dataset (200 synthetic support ticket records)
so I can run and test immediately.

Out of scope for now:
- OAuth integrations (Zendesk, Gong, Jira, Slack)
- Team management and per-seat billing
- Weekly digest emails and trend-shift detection
- Jira/Linear export (manual Markdown paste is MVP)
- Real-time streaming ingestion or background job queues

Rules:
- Inspect the codebase and summarize architecture before changing anything.
- Build only this chunk; build nothing out of scope; don't refactor unrelated files.
- Use mock data before real backend; add loading/error/empty states everywhere.
- Keep files under ~200 lines; route all sensitive API calls through the backend.
- After implementation: list changed files and explain how to test locally.
- Ask before adding libraries or changing the stack.
```

AI-Friendly Build Sequence

02 / 04

1
LLM prompt prototype (standalone script) — Python/Node script: read sample CSV → send batches to GPT-4o → cluster themes → output JSON with labels, quotes, scores
Goal
Validate LLM output quality before building UI; iterate prompts until 2+ PMs rate ≥ 4.0/5.0
Test before moving on
Run against 3 real customer datasets (500+ records each); collect quality ratings from 2–3 pilot PMs
2
Project setup + schema + auth — Next.js app scaffold, Supabase tables (users, orgs, uploads, records, analyses), RLS policies, magic-link auth
Goal
Foundation for everything else
Test before moving on
User can sign up, log in, and see an empty dashboard
3
CSV upload + text paste UI — File upload component, CSV parsing in browser, freeform text paste area, submit triggers API route
Goal
Get user data into the system
Test before moving on
Upload a 500-row CSV; records stored in Supabase with correct org isolation
4
LLM analysis API route — Reads uploaded records, batches them, calls GPT-4o with validated prompts, writes clustered results to analyses table, strips PII from quotes
Goal
Core analytic engine
Test before moving on
Upload sample data → analysis completes in under 5 min → themes in database are relevant and non-redundant
5
Signals dashboard — Page showing top 10 themes ranked by composite score; each row: label, count, trend direction badge, source mix indicator
Goal
Primary user-facing output
Test before moving on
Upload 500+ records → dashboard loads in < 2s → top 3 themes are clearly the most relevant
6
Theme detail view — Summary paragraph, evidence table (up to 5 anonymized quotes with source/date), recommendation paragraph
Goal
Backup credibility with evidence
Test before moving on
Click a theme → see quotes and recommendation → quotes contain no raw PII
7
Export + sample data mode — Copy-to-clipboard Markdown button; pre-loaded sample dataset with demo analysis
Goal
Close the "action" loop; enable cold-start demos
Test before moving on
Export looks clean in Notion/Linear paste; sample mode loads instantly without signup
8
Error/empty states + deploy — Empty state on no uploads, loading spinner during analysis, error on failed LLM call, deploy to Vercel + Supabase prod
Goal
Production-ready prototype
Test before moving on
Simulate: no data → see empty state; upload fails → see error; LLM timeout → see retry message

Functional Requirements

03 / 04

Core requirements

12 reqs
  1. 01Data source connection via OAuthThe system must allow authenticated users to connect Zendesk and Gong accounts via OAuth 2.0 flows. The connection must request the minimum scopes needed for ticket/call transcript read access. Successful connection must be confirmed with a green status indicator on the Integrations page.
  2. 02Historical data ingestionUpon first connection of a data source, the system must ingest the last 90 days of available records (support tickets with all thread replies; call transcripts with metadata: date, participant count, duration). The system must display a progress indicator during ingestion showing records processed out of estimated total.
  3. 03Incremental data syncAfter initial ingestion, the system must perform incremental syncs every 60 minutes, pulling only new or updated records since the last successful sync. Failed sync attempts must be retried up to 3 times with exponential backoff, then logged as errors visible to the admin user.
  4. 04Data normalizationThe system must normalize all ingested records into a unified internal schema with the following fields: record ID, source platform, ingestion timestamp, original timestamp, content body (text), customer identifier (if available from metadata), channel type (support ticket, chat transcript, sales call, internal doc), and any available sentiment metadata.
  5. 05LLM-powered theme clusteringThe system must analyze normalized records using an LLM to identify and cluster recurring customer pain-point themes. Each cluster must contain: a descriptive theme label (2–6 words), a summary paragraph (50–100 words), a frequency count of contributing records, a recency weight (more recent records score higher), and up to 5 anonymized representative quotes with source and date.
  6. 06Roadmap recommendation generationFor each of the top 10 ranked theme clusters, the system must generate a roadmap recommendation containing: a one-sentence prioritized action, a customer impact summary (number of unique customers, number of mentions across channels), a supporting evidence package (anonymized quotes, source attribution), and a suggested priority tier (High / Medium / Low) based on frequency and recency.
  7. 07Roadmap Signals dashboardThe system must display a main dashboard page ("Roadmap Signals") showing the top 10 pain-point clusters ranked by a composite score of frequency and recency. Each cluster row must show: theme label, frequency count, trend direction (↑ increasing / ↔ stable / ↓ decreasing), priority tier badge, and the number of contributing sources.
  8. 08Theme detail viewthe full summary paragraph, a line chart of mention frequency over the past 90 days, a table of anonymized quotes with source and date, the LLM-generated roadmap recommendation, and an "Export to Jira" action button.
  9. 09Trend-shift detection and alertingThe system must flag a theme cluster as "emerging" when its weekly mention frequency increases by 50% or more compared to the prior week. Emerging themes must be visually highlighted on the dashboard with an orange "Emerging" badge and included in the weekly digest.
  10. 10Jira exportUsers must be able to push a roadmap recommendation to Jira as a new Epic with the following fields populated: title (theme label), description (recommendation text + customer impact summary), and a linked attachment containing the evidence package as a formatted text document. The Jira connection must be established via OAuth and allow the user to select the target project.
  11. 11Weekly digest email00 AM (user-configurable timezone) listing the top 5 pain-point themes, any emerging trend shifts, and a link to the full dashboard. Users must be able to opt in/out from their notification settings.
  12. 12Team and seat managementThe system must support per-seat billing via Stripe. An admin user must be able to invite team members via email, assign roles (Admin, Viewer), and manage seat count. Viewer seats can browse and export but cannot manage integrations or billing. Seat limits must be enforced based on the active subscription.

States and errors

6 reqs
  1. 01Empty state — no data sources connectedWhen a user has registered but has not connected any data source, the dashboard must display an empty-state illustration with the message "Connect your first data source to start seeing signals," a prominent "Connect Data Source" button, and a brief explanation of what the platform does (3 sentences max).
  2. 02Loading state — initial ingestion in progressWhen a data source is connected and historical ingestion is running, the dashboard must display a loading skeleton with a progress message: "Analyzing your data — we've processed X of approximately Y records. This usually takes 15–45 minutes." The page must auto-refresh every 2 minutes without requiring manual reload.
  3. 03Error state — failed data source connectionIf an OAuth connection attempt fails (denied permissions, expired token, API error), the Integration page must display a red error badge on the affected source with the message "Connection failed — [specific reason]. Please retry." A "Retry Connection" button must be visible. The error must be logged for support diagnosis.
  4. 04Error state — sync failureIf an incremental sync fails after 3 retries, the affected data source must show a yellow warning badge with "Last sync failed — [date/time]. Data may be outdated." An admin notification (in-app banner) must appear. Users must be able to manually trigger a re-sync via a "Sync Now" button.
  5. 05Empty analysis resultsIf the LLM analysis completes but fewer than 3 distinct theme clusters are identified (due to insufficient data volume), the system must display a message: "Not enough data to generate reliable signals yet. We recommend at least 200 records across connected sources." with a link to connect additional sources or wait for more data.
  6. 06Rate limit or API quota exceededIf an external API (Zendesk, Gong, Jira) returns a rate limit (HTTP 429) or quota exceeded error, the system must pause the affected operation, display a user-friendly message: "We've temporarily paused syncing [source name] due to API limits. We'll automatically retry in [X minutes]." and resume automatically when the backoff period expires.

Constraints

5 reqs
  1. 01Dashboard performanceThe Roadmap Signals dashboard page must fully load (including ranked clusters and trend indicators) within 2 seconds on a standard broadband connection (≥ 10 Mbps). API responses powering the dashboard must return within 1 second for cached data.
  2. 02Data privacy and anonymizationcompany names, individual names, and email addresses must be redacted or replaced with placeholders. No raw personally identifiable information (PII) may be stored in the analysis results table — only in the raw ingestion table with appropriate access controls.
  3. 03AccessibilityAll UI pages must meet WCAG 2.1 AA standards. This includes keyboard navigability for all interactive elements, sufficient color contrast ratios (minimum 4.5:1), screen reader–compatible labels for charts and data visualizations, and visible focus indicators.
  4. 04Authentication and authorizationAll API endpoints must require a valid JWT token. Session tokens must expire after 24 hours of inactivity. Users can only access data and dashboards belonging to their own organization — no cross-tenant data leakage is permitted under any circumstances.
  5. 05LLM cost and latency budgetThe LLM analysis pipeline must process a batch of 1,000 records in under 10 minutes and cost less than $2.00 per batch (using current pricing for GPT-4 class models or equivalent). If a batch exceeds this budget, the system must chunk records more aggressively and process in parallel.

User Stories & Acceptance Criteria

04 / 04

US-001

Connect a Zendesk account

As a product manager, I want to connect my company's Zendesk account to Signal To Roadmap, So that the platform can ingest support tickets and start analyzing customer pain points.

Acceptance Criteria (5)
  • The user clicks "Connect Zendesk" and is redirected to Zendesk's OAuth authorization page.
  • After granting permission, the user is redirected back to Signal To Roadmap and the Zendesk integration shows a green "Connected" status.
  • The platform begins historical ingestion of the last 90 days of tickets and displays a progress indicator.
  • If the user denies OAuth permission, the integration shows a "Connection denied" error with a retry option.
  • The Zendesk OAuth flow requests only the minimum scopes necessary (read tickets + read users).
US-002

View the Roadmap Signals dashboard

As a product manager, I want to see a ranked list of recurring customer pain themes on a single dashboard, So that I can quickly understand what matters most to customers without reading individual tickets or call notes.

Acceptance Criteria (5)
  • The dashboard loads within 2 seconds on a standard broadband connection.
  • The top 10 pain-point clusters are displayed, each showing: theme label, frequency count, trend direction, priority tier badge, and number of contributing sources.
  • Clusters are ranked by a composite score of frequency and recency, with the highest-scoring cluster at the top.
  • If fewer than 3 clusters are identified, an empty analysis state message is displayed with guidance to connect more sources or wait for more data.
  • Each cluster row is clickable and navigates to the theme detail view.
US-003

Read a theme detail view with customer evidence

As a product manager, I want to click into a pain-point theme and see the supporting evidence — anonymized quotes, source attribution, and frequency over time, So that I can assess the credibility and urgency of the pain point.

Acceptance Criteria (4)
  • The detail page displays: theme summary, a line chart of mention frequency over 90 days, a table of up to 5 anonymized representative quotes with source and date, and the LLM-generated roadmap recommendation.
  • All customer names, company names, and email addresses are redacted from quotes.
  • The line chart accurately reflects the frequency data stored in the analysis database.
  • The page loads within 2 seconds.
US-004

Export a roadmap recommendation to Jira

As a product manager, I want to push a roadmap recommendation directly into Jira as an Epic, So that my engineering team has immediate context on the customer pain point they're solving.

Acceptance Criteria (5)
  • The user clicks "Export to Jira" on a theme detail view and is prompted to select a Jira project (via a dropdown populated from their connected Jira instance).
  • A new Jira Epic is created with: title = theme label, description = recommendation text + customer impact summary, and an attached evidence document containing anonymized quotes and signal counts.
  • The export completes within 10 seconds and shows a success confirmation with a link to the Jira Epic.
  • If the Jira connection is not established, the user is prompted to connect their Jira account via OAuth first.
  • If the Jira API returns an error, a user-friendly error is displayed with a retry option.
US-005

Receive a trend-shift alert

As a customer success manager, I want to be automatically notified when a customer pain point starts spiking in frequency, So that I can proactively alert the product team before it turns into churn.

Acceptance Criteria (4)
  • When a theme cluster's weekly frequency increases by 50% or more versus the prior week, it is flagged as "Emerging" on the dashboard.
  • The "Emerging" badge is visually distinct (orange) and appears on the cluster row in the dashboard.
  • If the user has enabled weekly digest emails, emerging themes are included in the digest with a special "Alert" callout.
  • If the user has connected Slack, an alert is posted to the configured Slack channel.
US-006

Onboard a new team member

As a product manager (Admin role), I want to invite a colleague to Signal To Roadmap with a Viewer role, So that they can see the Roadmap Signals dashboard without being able to modify integrations or billing.

Acceptance Criteria (5)
  • The Admin enters an email address and selects a role (Admin / Viewer) on the Team Settings page.
  • An invitation email is sent with a link to accept and create an account.
  • A Viewer can browse the dashboard, read theme details, and export to Jira but cannot manage data source connections, billing, or team invitations.
  • The seat count is updated and enforced against the subscription limit.
  • If the seat limit has been reached, the Admin sees a message: "You've reached your seat limit. Upgrade your plan to add more team members."
US-007

View the first-week experience (new user onboarding)

As a new user who just signed up, I want a guided onboarding experience that helps me connect my first data source and see my first insights, So that I can evaluate the product's value within my first session.

Acceptance Criteria (5)
  • After registration, the user is taken to a guided wizard (not an empty dashboard).
  • The wizard presents data source options with brief descriptions of what each source contributes.
  • The user connects at least one source (e.g., Zendesk) and the platform begins ingestion.
  • While ingestion runs, the user is shown a "What to expect" explainer page with a sample Roadmap Signals dashboard screenshot.
  • Once ingestion and analysis complete (progress bar reaches 100%), the user is automatically redirected to the Roadmap Signals dashboard with their real data.
US-008

Weekly digest email for PM

As a product manager, I want to receive a weekly email summary of the top 5 customer pain themes and any emerging trend shifts, So that I stay informed even during weeks when I don't open the platform.

Acceptance Criteria (4)
  • The digest email is sent every Monday at 8:00 AM local time (based on the user's configured timezone).
  • The email contains: top 5 theme clusters (label, frequency, trend direction), any themes flagged as "Emerging," a link to the full dashboard, and the user's name in the greeting.
  • The email includes a one-click "Unsubscribe" link that removes the user from digest emails while preserving their account.
  • The email displays correctly on desktop and mobile email clients (Gmail, Outlook, Apple Mail).