Client Scout Search

Your prompt from the orchestrator contains these fields. Parse them before searching:

4. Search Execution

For each project need in your needs_chunk, execute the search strategies appropriate to your wave type (defined in SEARCH-STRATEGIES.md).

4.1 General Search Flow

1. Construct search queries using templates from SEARCH-STRATEGIES.md
2. Execute WebSearch for each query
3. Evaluate results: Scan titles and snippets for funding program indicators
4. Follow promising links: Use WebFetch (or Playwright for JS-rendered pages) to verify
5. Extract basic program info: title, URL, source name, funding type guess, status guess
6. Check dedup: Compare against dedup_titles and dedup_urls
7. Assess match quality: Does this program plausibly match the client?

4.2 Content Retrieval Standard

Same as the extraction skill — hierarchical fallback:

HTML pages:

1. WebFetch(url) — check if content is substantive (not just nav/headers)
2. If empty/garbled → Playwright (browser_navigate + browser_snapshot)

PDF documents:

curl -sL -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" "PDF_URL" | python3 -c "
import sys, fitz
doc = fitz.open(stream=sys.stdin.buffer.read(), filetype='pdf')
for page in doc[:20]: print(page.get_text())
"

• ALWAYS include User-Agent header
• Skip PDFs > 10MB
• Extract first 20 pages only

Login-gated pages: Flag and skip — do not attempt to bypass.

4.3 Per-Source Search Depth

• Visit the source's website directly (if known) — check rebates/incentives/grants pages
• Follow links 1-2 levels deep from program listing pages
• Check DSIRE for this source (if utility or state agency)
• Execute 2-3 web search queries per project need per source
• If DAC client: Add environmental justice / IRA bonus credit searches

4.4 What Counts as a Finding

Include:

• Active grant programs, rebate programs, incentive programs, tax credit programs
• Programs accepting applications from the client's type
• Programs covering the client's geography
• Programs that fund at least one of your assigned project needs
• Open, upcoming, or rolling/continuous programs
• Closed-but-recurring programs (worth tracking for future rounds)

Exclude:

• News articles or press releases about funding (not the program itself)
• Residential-only programs (unless client type includes residential)
• Programs clearly for a different geography
• Programs for a completely different applicant type
• Informational pages that aren't actual funding programs
• Defunct/discontinued programs with no indication of future rounds

5. Dedup Protocol

Before including any finding in your output:

1. URL check: Is the URL (or a close variant) in dedup_urls?
2. Title check: Is a very similar title in dedup_titles? (fuzzy — account for slight naming differences)
3. If found in dedup list: Do NOT include as a new finding. Instead, add to your already_in_db list with the matching title/URL.

The orchestrator uses the already_in_db list to detect matching anomalies (Category 2 in the report).

6. Match Quality Assessment

For each finding, assess whether it would plausibly match the client using these criteria (mirrors the 4-criteria matching algorithm in evaluateMatch.js):

Assign a confidence level:

• high: All 4 criteria clearly match based on available information
• medium: 2-3 criteria match, others are unclear from search results alone
• low: Only 1 criterion clearly matches, significant uncertainty

7. Output Format

Return your findings as a structured report. The orchestrator will parse this.

=== WAVE REPORT: [wave_type] ===
Agent: [agent_name]
Needs chunk: [need1, need2, need3]
Queries executed: [N]
URLs evaluated: [N]

--- NEW FINDINGS ---

FINDING 1:
  title: [Official program name]
  url: [Primary URL]
  source_name: [Funding entity name]
  source_type: [Utility/County/State/Federal/Foundation]
  source_website: [Entity's main website]
  state_code: [XX]
  funding_type_guess: [Grant/Incentive/Rebate/Tax Credit/Loan]
  status_guess: [Open/Upcoming/Rolling/Closed-Recurring/Unknown]
  confidence: [high/medium/low]
  match_reasoning: [1-2 sentences: why this matches the client]
  matched_needs: [which project needs from your chunk this covers]
  program_urls: [array of URLs: main page, application page, PDF links]
  is_pdf: [true/false — whether primary content is a PDF]

FINDING 2:
  ...

--- ALREADY IN DB ---

EXISTING 1:
  found_title: [What you found]
  found_url: [URL you found]
  existing_match: [Title/URL from dedup list that matches]
  note: [Why you think this should/shouldn't be matching the client]

--- BONUS FINDS ---

BONUS 1:
  title: [Program name]
  url: [URL]
  source_name: [Entity name]
  note: [Why this is interesting even though it doesn't match THIS client]
  best_for: [What client types/geographies would benefit]

=== END WAVE REPORT ===

8. Error Handling

• WebSearch returns no results for a query: Try alternate query formulations (see SEARCH-STRATEGIES.md). After 3 attempts with no results, move to next need.
• WebFetch returns empty/error: Try Playwright. If both fail, note the URL as "could not access" and continue.
• PDF extraction fails: Note the URL as "PDF extraction failed" and continue.
• Source website is down: Note as "source website unavailable" and try web search queries instead.
• No findings for entire chunk: Report zero findings — that's a valid outcome. Don't invent findings.