Optimize qmd-docs workflows: explicitly instruct models to use qmd-query for doc search (#20987)

* Initial plan

* Optimize qmd-docs workflows with explicit qmd-query usage instructions

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Author: Copilot

.github/workflows/daily-doc-healer.md

@@ -97,7 +97,10 @@ For each issue that was NOT addressed by DDUw:
 
 1. Use `list_commits` and `get_commit` to review commits from the past 7 days.
 2. Determine whether any code change is directly related to the issue's subject matter (feature, flag, behavior described in the issue).
-3. Read the referenced documentation files to verify the gap exists today:
+3. **Use `qmd-query` to find relevant documentation files** for the feature or concept described in the issue — this is faster than using `find` and surfaces the most semantically relevant pages:
+   - e.g., `qmd-query("permissions workflow configuration")` or `qmd-query("safe-outputs create-pull-request")`
+   - Read the returned file paths to verify the documentation gap exists today
+4. Read the identified documentation files to verify the gap exists today:
 
 ```bash
 find docs/src/content/docs -name '*.md' -o -name '*.mdx'

.github/workflows/daily-doc-updater.md

@@ -125,12 +125,17 @@ Pay special attention to:
 
 Review the documentation in the `docs/src/content/docs/` directory:
 
+**First, use `qmd-query` to search for existing documentation** related to each identified change — this is faster and more accurate than browsing files manually:
+- For each new feature or change, run a targeted query: e.g., `qmd-query("engine configuration options")` or `qmd-query("permissions frontmatter field")`
+- Read the returned file paths to check if documentation already exists
+- Only resort to `find` for exhaustive listing when you need a complete inventory
+
 - Check if new features are already documented
 - Identify which documentation files need updates
 - Determine the appropriate documentation type (tutorial, how-to, reference, explanation)
 - Find the best location for new content
 
-Use bash commands to explore documentation structure:
+Use bash commands to explore documentation structure when needed:
 
 ```bash
 find docs/src/content/docs -name '*.md' -o -name '*.mdx'

.github/workflows/developer-docs-consolidator.md

@@ -103,6 +103,15 @@ If there's a previous run's data, load it to understand historical context:
 
 ### 1. Identify All Markdown Files
 
+Use `qmd-query` to discover relevant documentation and spec files before listing files with bash:
+
+```bash
+# Use qmd-query first to find semantically relevant files
+# Example: qmd-query("developer instructions code organization")
+# Example: qmd-query("project architecture patterns")
+# Then read the returned file paths to get full content
+```
+
 Find all `.md` files in the `scratchpad/` directory:
 
 ```bash

.github/workflows/dictation-prompt.md

@@ -56,9 +56,16 @@ Create a concise dictation instruction file at `skills/dictation/SKILL.md` that:
 
 ### 1. Scan Documentation for Project-Specific Glossary
 
-Scan documentation files in `docs/src/content/docs/` to extract approximately 1000 project-specific technical terms (950-1050 acceptable).
+Use `qmd-query` to efficiently discover documentation covering different areas of the project, then read the returned files to extract vocabulary. This is more targeted than scanning all files with `find`:
 
-**Focus areas:**
+- `qmd-query("workflow configuration frontmatter engine permissions")` — core workflow concepts
+- `qmd-query("safe-outputs create-pull-request tools MCP server")` — tools and integrations
+- `qmd-query("compilation CLI commands audit logs")` — CLI and developer tools
+- `qmd-query("network sandbox runtime activation triggers")` — advanced features
+
+Read each returned file path for its content, then also scan any remaining documentation files in `docs/src/content/docs/` to ensure broad coverage.
+
+**Focus areas for extraction:**
 - Configuration: safe-outputs, permissions, tools, cache-memory, toolset, frontmatter
 - Engines: copilot, claude, codex, custom
 - Bot mentions: @copilot (for GitHub issue assignment)

.github/workflows/glossary-maintainer.md

@@ -132,6 +132,11 @@ Read the current glossary:
 cat docs/src/content/docs/reference/glossary.md
 ```
 
+**For each candidate term, use `qmd-query` to find documentation that describes it** — this provides authoritative context for writing accurate definitions and reveals whether any documentation page already explains the term:
+- e.g., `qmd-query("safe-outputs create-pull-request")` to find pages describing that feature
+- e.g., `qmd-query("engine configuration copilot")` to find all documentation on engines
+- Read the returned file paths for full context before writing definitions
+
 **Check for:**
 - Terms that are missing from the glossary
 - Terms that need updated definitions

.github/workflows/shared/mcp/qmd-docs.md

@@ -49,4 +49,16 @@ mcp-scripts:
 
 <qmd>
 Use `qmd-query` to find relevant documentation files with a natural language request — it queries a local vector database of project docs, agents, and workflow files. Read the returned file paths to get full content.
+
+**Always use `qmd-query` first** when you need to find, verify, or search documentation:
+- **Before using `find` or `bash` to list files** — use `qmd-query` to discover the most relevant docs for a topic
+- **Before writing new content** — search first to check whether documentation already exists
+- **When identifying relevant files** — use it to narrow down which documentation pages cover a feature or concept
+- **When understanding a term or concept** — query to find authoritative documentation describing it
+
+**Usage tips:**
+- Use descriptive, natural language queries: e.g., `"how to configure MCP servers"` or `"safe-outputs create-pull-request options"` or `"permissions frontmatter field"`
+- Lower `min_score` (e.g., `0.3`) to get broader results; raise it (e.g., `0.6`) to get only the most closely matching files
+- Always read the returned file paths to get the full content — `qmd-query` returns paths only, not content
+- Combine multiple targeted queries rather than one broad query for better coverage
 </qmd>

.github/workflows/technical-doc-writer.md

@@ -108,7 +108,11 @@ When reviewing documentation for the specified topic in the **docs/** folder:
 
 1. **Analyze the topic** provided in the workflow input: "${{ github.event.inputs.topic }}"
 
-2. **Review relevant documentation files** in the docs/ folder related to the topic
+2. **Find relevant documentation files** using `qmd-query` before browsing files manually:
+   - Query with the topic: e.g., `qmd-query("${{ github.event.inputs.topic }}")`
+   - Run additional targeted queries if needed (e.g., `qmd-query("${{ github.event.inputs.topic }} examples")`)
+   - Read each returned file path to get the full content
+   - Then review those files in the docs/ folder
 
 3. **Make improvements** to the documentation as needed:
    - Fix clarity and conciseness issues

.github/workflows/unbloat-docs.md

@@ -152,7 +152,13 @@ This will help you avoid re-cleaning files that were recently processed.
 
 ### 2. Find Documentation Files
 
-Scan the `docs/` directory for markdown files, excluding code-generated files and blog posts:
+Use `qmd-query` to semantically search for documentation files that may contain bloat (verbose descriptions, repetitive patterns, excessive bullet points). This is faster and more targeted than listing all files:
+
+- Query for areas known to accumulate bloat: `qmd-query("verbose documentation long examples repeated patterns")`
+- Query for specific topics recently added: `qmd-query("recently added feature documentation")`
+- Read the returned file paths to assess their content
+
+Then scan the `docs/` directory for all markdown files, excluding code-generated files and blog posts:
 ```bash
 find docs/src/content/docs -path 'docs/src/content/docs/blog' -prune -o -name '*.md' -type f ! -name 'frontmatter-full.md' -print
 ```