From 879dc63a70c7fc64f2a6d63a1b8462243aa433a7 Mon Sep 17 00:00:00 2001 From: Mikael Hugo Date: Sun, 19 Apr 2026 08:47:57 +0200 Subject: [PATCH] prompts: add DeepWiki as the preferred docs-lookup path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All 9 research/planning/discuss prompts updated to put DeepWiki first in the docs-lookup order. Context7 becomes the fallback for package-registry-only libraries. Rationale: Context7 free tier is capped at 1000 req/month — a research-heavy auto loop can burn through that in a single session. DeepWiki has no cap and covers any GitHub-hosted library with AI-indexed answers, so it's strictly better as the default for the typical SF research path. Prompts touched: system.md, discuss.md, discuss-headless.md, plan-milestone.md, queue.md, research-milestone.md, research-slice.md, guided-discuss-milestone.md, guided-discuss-slice.md, guided-research-slice.md Each references the three DeepWiki tools — ask_question, read_wiki_structure, read_wiki_contents — and explicitly mentions the Context7 1000-req/month cap so models don't spend it wastefully. Co-Authored-By: Claude Sonnet 4.6 --- src/resources/extensions/sf/prompts/discuss-headless.md | 3 ++- src/resources/extensions/sf/prompts/discuss.md | 4 ++-- .../extensions/sf/prompts/guided-discuss-milestone.md | 4 ++-- src/resources/extensions/sf/prompts/guided-discuss-slice.md | 4 ++-- src/resources/extensions/sf/prompts/guided-research-slice.md | 2 +- src/resources/extensions/sf/prompts/plan-milestone.md | 2 +- src/resources/extensions/sf/prompts/queue.md | 4 ++-- src/resources/extensions/sf/prompts/research-milestone.md | 4 ++-- src/resources/extensions/sf/prompts/research-slice.md | 4 ++-- src/resources/extensions/sf/prompts/system.md | 2 +- 10 files changed, 17 insertions(+), 16 deletions(-) diff --git a/src/resources/extensions/sf/prompts/discuss-headless.md b/src/resources/extensions/sf/prompts/discuss-headless.md index 8f74b9fa4..414c0c1e0 100644 --- a/src/resources/extensions/sf/prompts/discuss-headless.md +++ b/src/resources/extensions/sf/prompts/discuss-headless.md @@ -76,7 +76,8 @@ Before anything else, form a diagnosis: What is the core challenge? What is brok - Use `rg`, `find`, `ast-grep`, `ls -la` for broad codebase mapping ### Step 2: Check library and ecosystem facts -- `resolve_library` / `get_library_docs` for any tech in the codebase +- **DeepWiki first:** `ask_question` / `read_wiki_structure` / `read_wiki_contents` for any GitHub-hosted library or framework — AI-indexed, no free-tier cap +- **Context7 fallback:** `resolve_library` / `get_library_docs` for npm/pypi/crates packages DeepWiki doesn't have. Free tier is 1000 req/month — spend those on cases DeepWiki can't cover - Understand version constraints, API capabilities, deprecation status - This tells you what's achievable without introducing new dependencies diff --git a/src/resources/extensions/sf/prompts/discuss.md b/src/resources/extensions/sf/prompts/discuss.md index 100960fea..6313701ca 100644 --- a/src/resources/extensions/sf/prompts/discuss.md +++ b/src/resources/extensions/sf/prompts/discuss.md @@ -35,11 +35,11 @@ After reflection is confirmed, decide the approach based on the actual scope — Before asking your first question, do a mandatory investigation pass. This is not optional. 1. **Scout the codebase** — `ls`, `find`, `rg`, or `scout` for broad unfamiliar areas. Understand what already exists, what patterns are established, what constraints current code imposes. -2. **Check library docs** — `resolve_library` / `get_library_docs` for any tech the user mentioned. Get current facts about capabilities, constraints, API shapes, version-specific behavior. +2. **Check library docs — DeepWiki first.** Use `ask_question` / `read_wiki_structure` / `read_wiki_contents` (DeepWiki) as the default for any GitHub-hosted library or framework the user mentioned. Fall back to `resolve_library` / `get_library_docs` (Context7) for npm/pypi/crates packages DeepWiki doesn't have. **Context7 free tier is capped at 1000 req/month — spend those on cases DeepWiki can't cover.** Get current facts about capabilities, constraints, API shapes, version-specific behavior. 3. **Web search** — `search-the-web` if the domain is unfamiliar, if you need current best practices, or if the user referenced external services/APIs you need facts about. Use `fetch_page` for full content when snippets aren't enough. **Web search budget:** You have a limited number of web searches per turn (typically 3-5). The discuss phase spans many turns (investigation, question rounds, focused research, requirements), so budget carefully: -- Prefer `resolve_library` / `get_library_docs` over `search-the-web` for library documentation — they don't consume the web search budget. +- Prefer DeepWiki → Context7 → `search-the-web` in that order for documentation lookups — DeepWiki and Context7 don't consume the web search budget. - Prefer `search_and_read` for one-shot topic research — it combines search + page fetch in a single call. - Target 2-3 web searches in the investigation pass. Save remaining budget for the focused research pass before roadmap creation. - Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. diff --git a/src/resources/extensions/sf/prompts/guided-discuss-milestone.md b/src/resources/extensions/sf/prompts/guided-discuss-milestone.md index 55903eb9d..c3ba272cb 100644 --- a/src/resources/extensions/sf/prompts/guided-discuss-milestone.md +++ b/src/resources/extensions/sf/prompts/guided-discuss-milestone.md @@ -17,10 +17,10 @@ Apply `pm-planning` skill thinking throughout: use Working Backwards to anchor o Do a lightweight targeted investigation so your questions are grounded in reality: - Scout the codebase (`rg`, `find`, or `scout`) to understand what already exists that this milestone touches or builds on - Check the roadmap context above (if present) to understand what surrounds this milestone -- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `search-the-web` for library documentation +- **Library docs — DeepWiki first.** Use `ask_question` / `read_wiki_structure` / `read_wiki_contents` (DeepWiki) for any GitHub-hosted library. Fall back to `resolve_library` / `get_library_docs` (Context7) only when DeepWiki doesn't have it (Context7 is capped at 1000 req/month free tier). - Identify the 3–5 biggest behavioural and architectural unknowns: things where the user's answer will materially change what gets built -**Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer `resolve_library` / `get_library_docs` for library documentation and `search_and_read` for one-shot topic research — they are more budget-efficient. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them. +**Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer DeepWiki → Context7 → web search in that order for documentation (DeepWiki and Context7 don't consume the web-search budget). Use `search_and_read` for one-shot topic research. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them. Do **not** go deep — just enough that your questions reflect what's actually true rather than what you assume. diff --git a/src/resources/extensions/sf/prompts/guided-discuss-slice.md b/src/resources/extensions/sf/prompts/guided-discuss-slice.md index 24f0bc155..59d5c4c29 100644 --- a/src/resources/extensions/sf/prompts/guided-discuss-slice.md +++ b/src/resources/extensions/sf/prompts/guided-discuss-slice.md @@ -13,10 +13,10 @@ Your goal is **not** to center the discussion on tech stack trivia, naming conve Do a lightweight targeted investigation so your questions are grounded in reality: - Scout the codebase (`rg`, `find`, or `scout` for broad unfamiliar areas) to understand what already exists that this slice touches or builds on - Check the roadmap context above to understand what surrounds this slice — what comes before, what depends on it -- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `search-the-web` for library documentation +- **Library docs — DeepWiki first.** Use `ask_question` / `read_wiki_structure` / `read_wiki_contents` (DeepWiki) for any GitHub-hosted library. Fall back to `resolve_library` / `get_library_docs` (Context7) only when DeepWiki doesn't have it (Context7 is capped at 1000 req/month free tier). - Identify the 3–5 biggest behavioural unknowns: things where the user's answer will materially change what gets built -**Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer `resolve_library` / `get_library_docs` for library documentation and `search_and_read` for one-shot topic research — they are more budget-efficient. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them. +**Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer DeepWiki → Context7 → web search in that order for documentation (DeepWiki and Context7 don't consume the web-search budget). Use `search_and_read` for one-shot topic research. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them. Do **not** go deep — just enough that your questions reflect what's actually true rather than what you assume. diff --git a/src/resources/extensions/sf/prompts/guided-research-slice.md b/src/resources/extensions/sf/prompts/guided-research-slice.md index cd5ea9a78..d1d9832c8 100644 --- a/src/resources/extensions/sf/prompts/guided-research-slice.md +++ b/src/resources/extensions/sf/prompts/guided-research-slice.md @@ -1,4 +1,4 @@ -Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.sf/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.sf/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. {{skillActivation}} Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs` — skip this for libraries already used in the codebase. Use the **Research** output template below. Call `sf_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "RESEARCH"`, and the research content — the tool writes the file to disk and persists to DB. +Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.sf/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.sf/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. {{skillActivation}} Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries DeepWiki-first: `ask_question` / `read_wiki_structure` / `read_wiki_contents` for any GitHub-hosted library; fall back to `resolve_library` / `get_library_docs` (Context7, capped at 1000 req/month free) for npm/pypi/crates packages DeepWiki doesn't have. Skip both for libraries already used in this codebase. Use the **Research** output template below. Call `sf_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "RESEARCH"`, and the research content — the tool writes the file to disk and persists to DB. **You are the scout.** A planner agent reads your output in a fresh context to decompose this slice into tasks. Write for the planner — surface key files, where the work divides naturally, what to build first, and how to verify. If the research doc is vague, the planner re-explores code you already read. If it's precise, the planner decomposes immediately. diff --git a/src/resources/extensions/sf/prompts/plan-milestone.md b/src/resources/extensions/sf/prompts/plan-milestone.md index b720a2345..0fbc67f7e 100644 --- a/src/resources/extensions/sf/prompts/plan-milestone.md +++ b/src/resources/extensions/sf/prompts/plan-milestone.md @@ -21,7 +21,7 @@ After you finish, each slice goes through its own plan → execute cycle. Slice Before decomposing, build your understanding: 1. **Codebase exploration.** For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in. -2. **Library docs.** Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase. +2. **Library docs — DeepWiki first.** Use `ask_question` / `read_wiki_structure` / `read_wiki_contents` (DeepWiki) as the default for any GitHub-hosted library. Fall back to `resolve_library` / `get_library_docs` (Context7) for npm/pypi/crates packages DeepWiki doesn't have. Context7 free tier is capped at 1000 req/month — spend those on cases DeepWiki can't cover. Skip both for libraries already used in this codebase. 3. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}} 4. **Requirements analysis.** If `.sf/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors. diff --git a/src/resources/extensions/sf/prompts/queue.md b/src/resources/extensions/sf/prompts/queue.md index 383b44f36..e1b4fb485 100644 --- a/src/resources/extensions/sf/prompts/queue.md +++ b/src/resources/extensions/sf/prompts/queue.md @@ -24,8 +24,8 @@ Never fabricate or simulate user input during this discussion. Never generate fa **Investigate between question rounds to make your questions smarter.** Before each round of questions, do enough lightweight research that your questions are grounded in reality — not guesses about what exists or what's possible. -- Check library docs (`resolve_library` / `get_library_docs`) when the user mentions tech you need current facts about — capabilities, constraints, API shapes, version-specific behavior -- Do web searches (`search-the-web`) to verify the landscape — what solutions exist, what's changed recently, what's the current best practice. Use `freshness` for recency-sensitive queries, `domain` to target specific sites. Use `fetch_page` to read the full content of promising URLs when snippets aren't enough. **Budget:** You have a limited number of web searches per turn (typically 3-5). Prefer `resolve_library` / `get_library_docs` for library documentation and `search_and_read` for one-shot topic research. Do NOT repeat the same or similar queries. Distribute searches across turns rather than clustering them. +- Check library docs **DeepWiki first** (`ask_question` / `read_wiki_structure` / `read_wiki_contents`) for any GitHub-hosted library or framework — AI-indexed, no free-tier cap. Fall back to Context7 (`resolve_library` / `get_library_docs`) for npm/pypi/crates packages DeepWiki doesn't cover. Context7 free tier is 1000 req/month — don't spend those on cases DeepWiki covers. +- Do web searches (`search-the-web`) to verify the landscape — what solutions exist, what's changed recently, what's the current best practice. Use `freshness` for recency-sensitive queries, `domain` to target specific sites. Use `fetch_page` to read the full content of promising URLs when snippets aren't enough. **Budget:** You have a limited number of web searches per turn (typically 3-5). Prefer DeepWiki → Context7 → web search for docs; use `search_and_read` for one-shot topic research. Do NOT repeat the same or similar queries. Distribute searches across turns rather than clustering them. - Scout the codebase (`ls`, `find`, `rg`, or `scout` for broad unfamiliar areas) to understand what already exists, what patterns are established, what constraints current code imposes Don't go deep — just enough that your next question reflects what's actually true rather than what you assume. diff --git a/src/resources/extensions/sf/prompts/research-milestone.md b/src/resources/extensions/sf/prompts/research-milestone.md index 99f3e4dcc..77b6a3ab5 100644 --- a/src/resources/extensions/sf/prompts/research-milestone.md +++ b/src/resources/extensions/sf/prompts/research-milestone.md @@ -32,8 +32,8 @@ Then research the codebase and relevant technologies. Narrate key findings and s 1. {{skillActivation}} 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}} 3. Explore relevant code. For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in. -4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase -5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — prefer `resolve_library` / `get_library_docs` for library documentation. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit. +4. **Documentation lookup — prefer DeepWiki first.** Use `ask_question` / `read_wiki_structure` / `read_wiki_contents` (DeepWiki) as the default for any GitHub-hosted library or framework — AI-indexed, no free-tier cap. Fall back to `resolve_library` → `get_library_docs` (Context7) for npm/pypi/crates packages DeepWiki doesn't have. **Context7 free tier is capped at 1000 requests/month — spend those on cases DeepWiki can't cover.** Skip both for libraries already used in this codebase. +5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — try DeepWiki → Context7 → web search in that order. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit. 6. Use the **Research** output template from the inlined context above — include only sections that have real content 7. If `.sf/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want. 8. Call `sf_summary_save` with `milestone_id: {{milestoneId}}`, `artifact_type: "RESEARCH"`, and the full research markdown as `content` — the tool computes the file path and persists to both DB and disk. diff --git a/src/resources/extensions/sf/prompts/research-slice.md b/src/resources/extensions/sf/prompts/research-slice.md index 9792dba49..b5be7b3c3 100644 --- a/src/resources/extensions/sf/prompts/research-slice.md +++ b/src/resources/extensions/sf/prompts/research-slice.md @@ -45,8 +45,8 @@ Research what this slice needs. Narrate key findings and surprises as you go — 1. {{skillActivation}} Reference specific rules from loaded skills in your findings where they inform the implementation approach. 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}} 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first. -4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase -5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — prefer `resolve_library` / `get_library_docs` for library documentation. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit. +4. **Documentation lookup — prefer DeepWiki first.** Use `ask_question` / `read_wiki_structure` / `read_wiki_contents` (DeepWiki) as the default for any GitHub-hosted library or framework — AI-indexed, no free-tier cap. Fall back to `resolve_library` → `get_library_docs` (Context7) for npm/pypi/crates packages DeepWiki doesn't have. **Context7 free tier is capped at 1000 requests/month — spend those on cases DeepWiki can't cover.** Skip both for libraries already used in this codebase. +5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — try DeepWiki → Context7 → web search in that order. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit. 6. Use the **Research** output template from the inlined context above — include only sections that have real content. The template is already inlined above; do NOT attempt to read any template file from disk (there is no `templates/SLICE-RESEARCH.md` — the correct template is already present in this prompt). 7. Call `sf_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "RESEARCH"`, and the full research markdown as `content` — the tool computes the file path and persists to both DB and disk. diff --git a/src/resources/extensions/sf/prompts/system.md b/src/resources/extensions/sf/prompts/system.md index b3a66eb2b..b3d835e7b 100644 --- a/src/resources/extensions/sf/prompts/system.md +++ b/src/resources/extensions/sf/prompts/system.md @@ -150,7 +150,7 @@ Templates showing the expected format for each artifact type are in: **Codebase exploration:** Use `subagent` with `scout` for broad unfamiliar subsystem mapping. Use `rg` for text search across files. Use `lsp` for structural navigation. Never read files one-by-one to "explore" — search first, then read what's relevant. -**Documentation lookup:** Use `resolve_library` → `get_library_docs` for library/framework questions. Start with `tokens=5000`. Never guess at API signatures from memory when docs are available. +**Documentation lookup:** Prefer `ask_question` / `read_wiki_contents` (DeepWiki) as the default — it's AI-indexed, covers any GitHub repo, and has no free-tier cap. Fall back to `resolve_library` → `get_library_docs` (Context7) for npm/pypi/crates packages when DeepWiki doesn't have the repo or you need the package-registry view. **Context7 free tier is capped at 1000 requests/month — spend those on cases DeepWiki can't cover.** Start Context7 calls with `tokens=5000`. Never guess at API signatures from memory when docs are available. **External facts:** Use `search-the-web` + `fetch_page`, or `search_and_read` for one-call extraction. Use `freshness` for recency. Never state current facts from training data without verification.