Dashboard/Scout/wiki/use-cases/validation-roadmap.md
Scout

wiki/use-cases/validation-roadmap.md

Scout Use-Case Validation Roadmap

Date: 2026-05-15

Purpose

Before building more Scout functionality, validate the product direction across multiple real use cases. Scout should not be planned around product scraping alone. It must support a broader class of web-to-record workflows:

  • product catalog extraction
  • job hunting and scheduled career monitoring
  • PRISM company/prospect intelligence
  • investor and financial document intelligence
  • generic web research and opportunity discovery
  • website/business quality analysis
  • documentation and knowledge-base extraction
  • news and social signal ingestion through appropriate providers

The goal is to pressure-test scenarios first, then create the development plan from validated requirements.

Core Question

Can Scout be a reusable engine for:

intent -> discovery -> fetch/provider selection -> extraction -> enrichment -> normalized records -> artifacts -> downstream use

Across many domains, not just ecommerce products.

Planning Principle

Do not build one-off scrapers per use case.

Build a shared platform with:

  • provider contracts
  • source provenance
  • domain schemas
  • extraction pipelines
  • quality scoring
  • artifact writing
  • evaluation fixtures
  • live smoke tests

Then add use-case modules on top.

Use-Case Families To Validate

1. Job Hunter / Career Monitoring

User scenario:

Run every morning against my target companies and find new jobs matching roles I care about.

Expanded interaction:

Scout should support an intake dialogue where the user enters:

  • target job titles
  • role families
  • keywords
  • industries or company categories
  • geography or remote preference
  • salary range
  • seniority level
  • required skills
  • excluded companies or roles
  • preferred companies if already known

Scout should then:

  1. Find companies that match the target area or industry.
  2. Return candidate company names, websites, careers pages, and confidence.
  3. Let the user approve, edit, or save the target company list.
  4. Find open roles at those companies matching the user's criteria.
  5. Track new, changed, and closed roles over scheduled daily runs.

Representative query:

Find product marketing, solutions engineering, developer advocate, and AI product roles at Adobe, Salesforce, Nike, OpenAI, and Shopify. Return only new jobs since yesterday.

Discovery-first query:

I am looking for AI product marketing or developer advocate roles, remote or New York, salary above $160k. First find companies hiring in this area, then check those companies for matching jobs every day.

Scout output:

  • JobPostingRecord
  • CompanyJobRun
  • NewJobDelta
  • JobSearchProfile
  • TargetCompanyRecord

Fields:

  • search profile fields:
  • desired titles
  • role families
  • keywords
  • salary range
  • locations
  • seniority
  • target industries
  • required skills
  • excluded terms
  • target company fields:
  • company
  • website
  • careers URL
  • LinkedIn URL when discoverable
  • industry/category
  • reason matched
  • confidence
  • company
  • title
  • job ID
  • location
  • remote/hybrid/onsite
  • salary range
  • department
  • description
  • responsibilities
  • qualifications
  • apply URL
  • ATS platform
  • posted date
  • first seen date
  • last seen date
  • matched user criteria

Pressure tests:

  • Can Scout collect job preferences through an intake dialogue?
  • Can Scout discover companies in a target role/industry area before job search?
  • Can Scout return a reviewable target company list before monitoring?
  • Can Scout discover official careers pages?
  • Can Scout detect ATS providers?
  • Can Scout search jobs by role?
  • Can Scout detect new versus already-seen jobs?
  • Can Scout run on a schedule and write a daily delta artifact?
  • Can Scout avoid applying to jobs or taking account actions?

Example targets:

  • Adobe Careers
  • Salesforce Careers
  • Nike Careers
  • Shopify Careers
  • Workday Careers

Example company-discovery themes:

  • AI product marketing roles
  • developer advocate roles
  • solutions engineering roles
  • ecommerce search/personalization roles
  • remote-first SaaS companies hiring senior product roles

Key risk:

ATS platforms vary heavily. Workday, Greenhouse, Lever, Ashby, SmartRecruiters, and custom careers pages need provider-specific handling. Company discovery can drift into generic search results unless Scout preserves why each company was selected and lets the user approve the target list.

2. PRISM Company / Prospect Intelligence

User scenario:

I want to research Nike as an Algolia prospect: company overview, executives, investor priorities, hiring signals, ecommerce catalog, search experience, and recent news.

Scout output:

  • CompanyPageRecord
  • ExecutiveRecord
  • InvestorDocumentRecord
  • JobPostingRecord
  • ProductRecord
  • NewsArticleRecord
  • SearchExperienceRecord
  • EvidenceBundle
  • CompanySocialRecord

Pressure tests:

  • Can Scout discover official company, about, leadership, investor, careers, and newsroom pages?
  • Can Scout discover the company's canonical website?
  • Can Scout discover the company's official LinkedIn page?
  • Can Scout discover official company social channels?
  • Can Scout discover executives and their LinkedIn/profile URLs when available?
  • Can Scout collect evidence without doing final strategy synthesis?
  • Can Scout preserve provenance for every fact?
  • Can PRISM consume Scout records without custom glue per source?
  • Can Scout distinguish official sources from third-party sources?

Required PRISM fields:

  • company name
  • canonical website
  • company LinkedIn URL
  • company X/Twitter URL when available
  • company YouTube URL when available
  • company Instagram/TikTok/Facebook URLs when relevant
  • about/company overview URL
  • leadership/executive page URL
  • executive names
  • executive titles
  • executive bios
  • executive LinkedIn/profile URLs when available
  • investor relations URL
  • careers URL
  • newsroom/press URL
  • ecommerce/product catalog URLs when relevant
  • source provenance and confidence for every discovered URL

Example targets:

  • Nike
  • Sephora
  • Best Buy
  • Williams-Sonoma
  • Lululemon

Key risk:

This is a composite workflow. It should orchestrate multiple modules but keep extraction records separate from strategic interpretation.

3. Investor And Financial Intelligence

User scenario:

Get investor documents, 10-K/10-Q filings, annual reports, presentations, risk factors, revenue numbers, and executive quotes.

Scout output:

  • InvestorDocumentRecord
  • FinancialMetricRecord
  • RiskFactorRecord
  • ExecutiveQuoteRecord
  • PresentationRecord

Pressure tests:

  • Can Scout find official investor pages?
  • Can Scout find and parse PDFs?
  • Can Scout normalize financial periods, currencies, and units?
  • Can Scout extract numbers with source provenance?
  • Can Scout avoid naked metrics with no evidence?

Example targets:

  • Nike investor relations
  • Adobe investor relations
  • Salesforce investor relations
  • Apple investor relations
  • Microsoft investor relations

Key risk:

PDF/document parsing and numeric provenance must be rigorous. This use case needs stronger validation than ordinary page scraping.

4. Product Catalog / Algolia Records

User scenario:

Find the top categories for Estee Lauder and get 10 products each with all attributes, price, color, review, everything. Then get top 10 best sellers as well.

Scout output:

  • ProductRecord
  • CategoryRecord
  • ProductRunManifest

Pressure tests:

  • Can Scout fetch category pages through the best available provider?
  • Can Scout extract product cards?
  • Can Scout enrich PDP attributes?
  • Can Scout merge variants, prices, ratings, colors, images, and badges?
  • Can Scout write Algolia-ready records?
  • Can Scout report blocked pages clearly?

Example targets:

  • Estee Lauder
  • Lacoste
  • Nike
  • Sephora
  • Patagonia

Key risk:

Hard sites may block local Crawl4AI. Skill-host WebFetch/browser providers and standalone CDP/profile/proxy strategies are required.

5. Generic Web Research / "Find Things Online"

User scenario:

I have a business idea. Find companies in this space, collect their websites, summarize what they offer, and identify gaps.

Scout output:

  • SearchResultRecord
  • CompanyPageRecord
  • WebsiteAssessmentRecord
  • OpportunityEvidenceRecord

Pressure tests:

  • Can Scout use search to discover candidate companies?
  • Can Scout fetch each website/about/product page?
  • Can Scout extract comparable structured fields?
  • Can Scout score website quality using explicit criteria?
  • Can Scout produce a dataset that another layer can analyze?

Example target categories:

  • local service businesses
  • niche SaaS tools
  • agency websites
  • ecommerce stores
  • healthcare/clinic sites

Key risk:

"Bad website" is subjective. Scout should extract observable evidence and maybe compute heuristic scores, but the business judgment layer should be separate.

6. Website Quality / Competitive Gap Analysis

User scenario:

Find companies whose websites are weak, outdated, slow, thin, hard to navigate, or missing key conversion elements.

Scout output:

  • WebsiteAssessmentRecord
  • PageQualitySignal
  • CompetitorComparisonRecord

Potential signals:

  • missing clear value proposition
  • outdated design indicators
  • broken links
  • poor mobile readability
  • no pricing/contact CTA
  • missing structured data
  • weak page speed or accessibility score where measurable
  • thin content
  • confusing navigation

Pressure tests:

  • Can Scout collect page snapshots and text?
  • Can Scout run objective checks before subjective scoring?
  • Can Scout compare multiple websites with the same rubric?
  • Can Scout preserve examples/screenshots as evidence?

Example targets:

  • local dental clinics
  • small law firms
  • regional HVAC/plumbing companies
  • boutique agencies
  • niche B2B SaaS websites

Key risk:

This use case may require browser screenshots, Lighthouse-like audits, and a rubric. It should not rely only on LLM opinion.

7. Documentation / Knowledge Base Extraction

User scenario:

Extract a docs site into clean records for search or RAG.

Scout output:

  • DocumentationPageRecord
  • CodeExampleRecord
  • APIMethodRecord

Pressure tests:

  • Can Scout preserve page hierarchy?
  • Can Scout preserve code examples?
  • Can Scout handle docs sitemap/llms.txt?
  • Can Scout chunk without losing context?
  • Can Scout write Algolia-ready docs records?

Example targets:

  • Algolia docs
  • Stripe docs
  • Shopify developer docs
  • Vercel docs
  • OpenAI docs

Key risk:

Docs extraction requires careful chunking and code preservation. Generic markdown cleanup can destroy useful structure.

8. Newsroom / Signal Monitoring

User scenario:

Monitor target company newsrooms for launches, leadership changes, AI/search investments, partnerships, and market expansion.

Scout output:

  • NewsArticleRecord
  • CompanySignalRecord

Pressure tests:

  • Can Scout discover official newsrooms?
  • Can Scout parse dates?
  • Can Scout filter by recency?
  • Can Scout classify signal type?
  • Can Scout dedupe syndicated articles?

Example targets:

  • Nike newsroom
  • Adobe News
  • Salesforce News
  • Shopify News
  • Microsoft blogs

Key risk:

Date parsing and recency filtering must be deterministic. News changes frequently, so live tests need tolerant assertions.

9. Social Signal Normalization

User scenario:

Get recent LinkedIn/X posts for a company and normalize them into topic and signal records.

Scout output:

  • SocialSignalRecord

Pressure tests:

  • Can Scout ingest provider output?
  • Can Scout normalize posts from different platforms?
  • Can Scout classify topics and source provenance?
  • Can Scout avoid pretending raw Crawl4AI can reliably scrape LinkedIn/X?

Example targets:

  • Nike LinkedIn/X
  • Adobe LinkedIn/X
  • Salesforce LinkedIn/X
  • Shopify LinkedIn/X
  • Algolia LinkedIn/X

Key risk:

Scout should not treat LinkedIn/X as normal websites. Use provider integrations, exports, APIs, or explicit browser sessions.

Cross-Cutting Requirements

Provider Capability Matrix

Every use case must declare which providers can support it.

Provider examples:

  • WebSearch
  • WebFetch
  • Crawl4AI
  • browser/session
  • CDP/profile
  • saved HTML/DOM
  • PDF parser
  • ATS adapter
  • social provider
  • official API

Record Schemas

Each use case must define:

  • required fields
  • optional fields
  • derived fields
  • source/provenance fields
  • confidence/completeness scoring

Artifact Contract

Every run writes:

  • manifest.json
  • records.json
  • records.jsonl
  • source_pages.json
  • blocked_pages.json
  • extraction_report.md

Use-case-specific artifacts can be added later.

Evaluation Harness

For each use case:

  • fixture tests from saved source content
  • parser/normalizer unit tests
  • artifact contract tests
  • live smoke tests
  • blocked/partial-success tests

Scheduling

Scheduling matters especially for:

  • job hunter
  • newsroom monitoring
  • social monitoring
  • prospect research refresh
  • product catalog refresh

Scout should not own all scheduling in v1, but it must be schedule-friendly:

  • deterministic CLI commands
  • stable output directories
  • run manifests
  • deltas from prior run
  • exit codes

Create a validation plan before implementation:

  1. Pick 5 priority use cases.
  2. For each, select 3-5 target websites.
  3. For each target, define one query, expected provider path, and expected record shape.
  4. Run a manual provider dry run.
  5. Save source fixtures.
  6. Convert successful dry runs into tests.
  7. Only then build provider interfaces and extraction modules.

Priority Recommendation

Do not build UC-01 alone.

Build the platform skeleton around three vertical slices:

  1. Product catalog extraction.
  2. Careers/job monitoring.
  3. PRISM company intelligence.

These three cover the most important architectural pressure:

  • listing/detail enrichment
  • scheduled delta runs
  • composite evidence bundles
  • provider fallback
  • structured records
  • artifacts