PRD: Product Requirements Document

Created the draft PRD with labeled assumptions and five HTML mockups. Section, link, and script syntax checks passed.

Files in the current directory

• ./saved-search-alerts-prd.md
• ./search-inline.html
• ./search-modal.html
• ./saved-searches.html
• ./email-preferences.html
• ./alert-previews.html
• ./validation-report.json

---

1. Saved-search alerts

2. Description

Let buyers save search criteria and receive alerts when new listings match. Buyers choose email, push, or both. They can pause, change, or delete each saved search.

Assumption register: A1 covers ownership. A2 covers audience and existing marketplace capabilities. A3 covers all proposed behavior in §7 and §11. A4 covers measurement definitions and targets. A5 covers experiment design and timing. A6 covers launch responsibilities and dependencies. Each is a proposal, not a verified fact. Requirements below are normative within this draft, and rest on these labeled assumptions.

3. Problem

Known: The request states: “Users on our listings marketplace want to save a search and get a push or email when a new listing matches it.”

Assumption A2: Buyers repeat searches because relevant inventory arrives over time. Manual checks cost time and can miss useful listings. Primary actors are buyers. Sellers benefit from qualified visits. Support handles missing or unwanted alerts.

4. Why

Known: No codebase, analytics, research, prior PRD, or design was supplied. No stakeholder is available during this run. The workspace contains no product document to extend. No external market claims are used.

Assumption A2: Repeat searchers need timely discovery more than another broad promotional message. Existing accounts, search filters, listing pages, verified email, and a push-capable app are available. Confirm these before committing a launch date.

Before launch, pull 28 days of repeat-search rates, new-listing volume per common search, return visits, and notification opt-out rates. Interview five repeat searchers about urgency and acceptable frequency. Owner: proposed product lead (Assumption A6). No cross-team requirements have been received.

5. Success

All definitions and targets below are

Assumption A4. Baselines are unknown unless stated. Let L be the actual beta start. Report sample sizes with each rate. Exclude staff and test accounts.

Provider acceptance does not prove receipt or attention. Do not use email opens as the success measure. Instrument acquisition (entry exposure), activation (alert enabled), value (attributed matched-listing view), and retention (another attributed view on a later day within 30 days). Record channel, experiment group, saved-search identifier, and event time. Avoid raw queries or email addresses in analytics. Missing attribution is reported separately.

6. Audience

Assumption A2: Start with signed-in buyers who repeat a specific keyword and filter combination. Include low-inventory searches with zero current results. Guest users can start setup, then sign in and return with their criteria intact. Sellers are not the target audience.

Assumption A3: Use the search-results entry point and account navigation for discovery. Alerts are user-requested lifecycle messages. Do not enroll users by default or add promotional messages. Segment readouts by channel and inventory volume. Do not infer sensitive interests for targeting.

7. What

All product decisions in this section are Assumption A3, pending review.

Key features

User journeys

flowchart TD
    A[Search results, including zero results] --> B[Save search]
    B --> C{Signed in?}
    C -->|No| D[Sign in and restore criteria]
    C -->|Yes| E[Review criteria and channels]
    D --> E
    E --> F{Channel available?}
    F -->|No| G[Resolve permission or save with alerts off]
    F -->|Yes| H[Save and confirm]
    G --> H
    H --> I[Manage saved searches]
    I --> J[Edit, pause, resume, or delete]
    H --> K[New matching listing]
    K --> L[Email or push]
    L --> M[Listing or matching results]
    L --> N[Turn off email alerts]

• Entry: search results or empty results → setup → sign-in if needed → return to setup.
• Cancel or failed sign-in: return to results; create nothing. Preserve the draft while the session remains open.
• Confirm: save once, show success and a Manage saved searches link. On failure, retain inputs and offer Retry.
• No eligible channel: explain why; allow saving with alerts off. Never show “alerts on” without an eligible selected channel.
• Notification: one listing opens that listing; multiple listings open existing results for the saved criteria. Sign-in, if required, preserves the destination.
• Listing removed after send: explain “This listing is no longer available” and offer current matching results.
• Management: edit and confirm → updated row; cancel → original row. Pause/resume updates the state. Delete → confirmation → removal or cancellation.
• Email opt-out: open scoped preference page → turn off this search’s email or all saved-search email → confirmation. Push remains unchanged. Existing provider-handed messages may still arrive.

Design

Rough, self-contained HTML mockups are the review artifacts. Each opens directly in a browser. Sample listings and counts are fictional.

Assumption A3: choose inline setup for the first release. Review the modal alternative before approval. Existing sign-in, email verification, operating-system permission prompts, search results, and available listing detail screens are reused. Their existence is Assumption A2. If absent, revise scope and mockups before implementation.

Use clear labels, keyboard access, visible focus, and readable mobile layouts. Announce save and error status. Do not indicate state by color alone.

Product copy

• Entry: “Save search”. Empty results: “No matches yet. Save this search to hear about new listings.”
• Setup: “Get alerts for new matches”. Channels: “Email” and “Push”. Helper: “Choose either, both, or save with alerts off.”
• Success: “Search saved. Alerts are on.” Without channels: “Search saved. Alerts are off.”
• Permission denied: “Push is blocked. Enable notifications in device settings or choose email.”
• Unverified email: “Verify your email to enable email alerts.”
• Failure: “We could not save your search. Your changes are still here. Try again.”
• Limit: “You have 20 saved searches. Delete one to save another.”
• Delete: “Delete this saved search? Its alerts will stop.” Buttons: “Keep search” and “Delete search”.

Out of scope

Exclude price-drop alerts, listing-edit alerts, existing-inventory backfill, SMS, seller alerts, paid tiers, recommendations, shared searches, and custom schedules. Exclude changes to search ranking or seller publication rules.

Future considerations

Consider daily digests, quiet hours, and user-set frequency after measuring volume and opt-outs. Do not promise them at launch.

Constraints and dependencies

Assumption A2: current search criteria can be reproduced and listing identity persists across edits. Assumption A6: product, engineering, design, support, and messaging owners can review the draft. Email and push delivery capabilities are unverified. No vendor, staffing level, or delivery date is confirmed.

Edge and corner cases

8. How

Assumption A5: Gate the feature with a configuration toggle, initially off. Pilot with 10% of eligible signed-in buyers; assign a random equal-sized holdout without the new entry point. Keep assignments stable. Compare return listing views per eligible buyer over 30 days as a secondary experiment outcome. The primary metric is descriptive within the enabled cohort. Do not claim causal impact from it.

Check activation and guardrails after 14 days. Expand only after the 30-day readout meets targets and the reviewer approves. If the primary denominator is below 200 users, extend beta; this is an operational threshold, not a power calculation. Determine statistical power after baseline data is available. Stop expansion for incorrect recipients or persistent duplicates. A delivery toggle stops new sends while management remains available.

9. When

All dates are Assumption A5, tentative and dependent on capacity and feasibility.

These are product milestones. Implementation order belongs to the ERD.

10. Open questions and notes for architecture

Product questions

Open Question: Who owns the feature and reviews the eventual PR? Interim assumption: product lead plus an assigned engineering reviewer.

Open Question: Is fifteen-minute batching acceptable for this marketplace? Interim assumption: yes; validate with repeat searchers.

• Open Question: Do users prefer one device or all devices? Interim assumption: one recent permitted device.

Risk: A four-message cap can delay urgent discoveries. Compare high-volume cohort opt-outs and discovery outcomes before expanding.

• Risk: Low inventory can make the primary cohort small. Report excluded users with no eligible matches separately.

Architecture notes for the ERD

Resolve matching consistency, publication identity, permission changes, deduplication across searches, batching, rate caps, retries, and cancellation boundaries. Define secure destination links, email opt-out tokens, event attribution, retention, and account deletion. Check existing search and messaging capabilities first. Prototype matching feasibility if reliable publication events or equivalent saved-filter evaluation are unavailable. No service topology or vendor is selected here.

11. Non-visual product requirements

All copy and delivery decisions are

Assumption A3. Counts use available matches at handoff. Do not place precise private location data in lock-screen copy. Use the saved name only inside signed-in product screens. Email includes a scoped opt-out link and account preferences link.

Email shows listing title, displayed price/currency, and public location when available. Missing optional details are omitted, never invented. No automatic fallback from push to email without the user's email selection. Resume after a global email opt-out requires explicit email opt-in on a saved search; preserve the disabled state for other searches. Unsubscribe never changes transactional account messages.

12. Third-party tools

Assumption A6: Existing email and push providers will be reused. No providers are known or selected. Email depends on sending, failure feedback, and opt-out support. Push depends on platform permission and delivery feedback. Validate these in the ERD. This document authorizes no installation or provider purchase.

13. Is seeding required?

Assumption A6: No fake production listings or pre-created user searches are needed. Use clearly marked test accounts and synthetic listings in staging. Support needs examples of delayed, blocked, paused, and opted-out alerts before beta.

14. Go to market

Assumption A6: Introduce the feature at search results and in saved-search navigation. Explain that users choose channels. Avoid a broad email announcement until beta validates value.

Launch checklist

• Assign owner and reviewer; record explicit product approval.
• Confirm assumed account, search, email, and push capabilities.
• Review matching and notification-copy examples with target buyers.
• Verify full journeys in staging: save → new listing → each selected channel → correct destination.
• Verify no-alert cases: old inventory, edit, wrong filter, paused search, opt-out, and unavailable listing.
• Verify duplicate search, overlapping matches, rate cap, retries, permissions, and deletion races.
• Retain a repeatable E2E report with test data, expected results, timestamps, and delivery evidence.
• Verify metrics, privacy handling, support guidance, and the delivery stop control.

Known: This run produces a PRD and mockups only. No production feature or integrated delivery test exists. Document validation cannot establish implementation readiness.

15. Glossary

• Saved search: A named set of search criteria owned by a buyer.
• Eligible match: A newly published, public listing that matches an active search after activation.
• Active alert: A saved search with at least one eligible enabled channel and no pause.
• Provider acceptance: The messaging provider accepts a send request; receipt is not guaranteed.
• Handoff: The point after which a message may no longer be cancelable.
• Holdout: Eligible users assigned to the existing experience during the experiment.

No template sections were skipped. Next: after explicit PRD approval and a request for technical planning, use the erd skill. Carry forward exclusions and constraints, and resolve §10. Keep this document as the product source of truth.