Patrick Plate
100 lines
4.2 KiB
Markdown
100 lines
4.2 KiB
Markdown
# Web Research Rules — Use webscraper_search_hint Proactively
|
||
|
||
## Rule: Search Before Asking
|
||
|
||
Before asking Patrick for information about a library, framework, API, technology, or error —
|
||
**always try `webscraper_search_hint` first**.
|
||
|
||
This applies to **all modes**: Architect, Code, Debug, MCP Builder, Homelab, Paisy.
|
||
|
||
### Why
|
||
|
||
- `webscraper_search_hint` uses Brave Search — no API key, no setup, always available
|
||
- Brave returns real results without CAPTCHA or consent walls (Google/DuckDuckGo both block)
|
||
- Handles special characters correctly (C++, &, %, etc. — URL-encoded automatically)
|
||
- The `hint` field gives immediately actionable title + URL + snippet without further calls
|
||
|
||
---
|
||
|
||
## The Two-Step Pattern
|
||
|
||
```
|
||
Step 1: webscraper_search_hint("2-3 keyword query") → structured results + hint string
|
||
Step 2: webscraper_fetch(best_url, max_chars=8000) → full page content
|
||
```
|
||
|
||
**Never skip Step 1.** It costs one tool call and often reveals the exact page to read.
|
||
|
||
### Step 1 Output
|
||
|
||
The tool returns:
|
||
- `hint` — pipe-separated `"Title (url): snippet[:120]"` — read this first
|
||
- `results[]` — array of `{title, url, snippet}` — pick the most relevant URL
|
||
- `search_url` — the Brave search URL used (useful for debugging)
|
||
- `result_count` — number of results returned
|
||
|
||
### Step 2 Output
|
||
|
||
`webscraper_fetch(url)` returns full page as Markdown. Use `max_chars` to control size
|
||
(default 5000; use 8000–12000 for deep doc reads).
|
||
|
||
---
|
||
|
||
## Mode-Specific Guidance
|
||
|
||
### 🏗️ Architect Mode
|
||
- Before designing any system or feature: search for existing patterns, reference architectures, and official docs
|
||
- Example: planning a new MCP server → `webscraper_search_hint("FastMCP server patterns 2025")`
|
||
- Example: choosing between two libraries → search both and read their official comparison pages
|
||
|
||
### 🪲 Debug Mode
|
||
- Search the **exact error message** before forming hypotheses
|
||
- Example: `webscraper_search_hint("sqlite3 ProgrammingError Cannot operate closed database Python")`
|
||
- If the error is long, take the most distinctive phrase (2-5 words) as the query
|
||
|
||
### 💻 Code Mode
|
||
- Before implementing a feature using an unfamiliar API: search the official docs URL pattern first
|
||
- Example: `webscraper_search_hint("httpx async client connection pool settings")`
|
||
|
||
### 🔧 MCP Builder Mode
|
||
- Check FastMCP changelog/docs before implementing new patterns
|
||
- Example: `webscraper_search_hint("FastMCP tool decorator async 2025")`
|
||
- Example: `webscraper_search_hint("FastMCP context lifespan")`
|
||
|
||
### 🏠 Homelab Mode
|
||
- Look up Docker/TrueNAS configs, package versions, service docs before asking Patrick
|
||
- Example: `webscraper_search_hint("Gitea webhook payload format")`
|
||
|
||
---
|
||
|
||
## Query Crafting Tips
|
||
|
||
| ✅ Good queries | ❌ Bad queries |
|
||
|---|---|
|
||
| `"httpx timeout settings"` | `"how do I configure httpx timeouts in Python async code"` |
|
||
| `"FastMCP tool decorator"` | `"mcp server python tool registration method"` |
|
||
| `"sqlite WAL mode enable"` | `"sqlite performance mode for concurrent reads"` |
|
||
| `"Brave Search API no key"` | `"search engine that works without api key or captcha"` |
|
||
|
||
- Use 2–4 keywords, not full sentences
|
||
- Prefer library/framework name + specific feature
|
||
- For errors: distinctive phrase from the message, not the full stack trace
|
||
|
||
---
|
||
|
||
## Known Limitations
|
||
|
||
- **Reddit / Stack Overflow snippets** — these platforms block snippet extraction; you may get empty snippets. The URL is still valid — fetch it directly if needed.
|
||
- **Brave CSS selector fragility** — Brave uses Svelte-generated class names that change. If `webscraper_search_hint` returns 0 results unexpectedly, the scraper's CSS selectors may need updating. Last verified working: 2026-04-05.
|
||
- **Use sparingly** — one search call per research task to orient; then fetch specific pages. Don't call it in a loop.
|
||
|
||
---
|
||
|
||
## Anti-Patterns to Avoid
|
||
|
||
- ❌ Asking Patrick "what's the FastMCP syntax for X?" before searching
|
||
- ❌ Designing architecture without looking up existing solutions first
|
||
- ❌ Forming a debug hypothesis without searching the error message
|
||
- ❌ Writing code against an API from memory without verifying current docs
|
||
- ❌ Calling `webscraper_search_hint` more than 2-3 times for the same topic (broaden/narrow the query instead)
|