From 9c7103ffa014d0d09ce8485ddb0bfc3902100575 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 14 Mar 2026 21:15:33 +0000 Subject: [PATCH 1/2] Initial plan From 4ec043423b4de5d1bd128858be0b60c848705fc9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 14 Mar 2026 21:25:15 +0000 Subject: [PATCH 2/2] Optimize qmd-docs workflows with explicit qmd-query usage instructions Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .github/workflows/daily-doc-healer.md | 5 ++++- .github/workflows/daily-doc-updater.md | 7 ++++++- .github/workflows/developer-docs-consolidator.md | 9 +++++++++ .github/workflows/dictation-prompt.md | 11 +++++++++-- .github/workflows/glossary-maintainer.md | 5 +++++ .github/workflows/shared/mcp/qmd-docs.md | 12 ++++++++++++ .github/workflows/technical-doc-writer.md | 6 +++++- .github/workflows/unbloat-docs.md | 8 +++++++- 8 files changed, 57 insertions(+), 6 deletions(-) diff --git a/.github/workflows/daily-doc-healer.md b/.github/workflows/daily-doc-healer.md index 820cd1f69e..28a6d2625e 100644 --- a/.github/workflows/daily-doc-healer.md +++ b/.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' diff --git a/.github/workflows/daily-doc-updater.md b/.github/workflows/daily-doc-updater.md index 0589afff68..81cb2437a1 100644 --- a/.github/workflows/daily-doc-updater.md +++ b/.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' diff --git a/.github/workflows/developer-docs-consolidator.md b/.github/workflows/developer-docs-consolidator.md index ca09807e77..309ae6ac76 100644 --- a/.github/workflows/developer-docs-consolidator.md +++ b/.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 diff --git a/.github/workflows/dictation-prompt.md b/.github/workflows/dictation-prompt.md index a2f4efef85..55179f46a1 100644 --- a/.github/workflows/dictation-prompt.md +++ b/.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) diff --git a/.github/workflows/glossary-maintainer.md b/.github/workflows/glossary-maintainer.md index 9470a5fd17..30904cd7d7 100644 --- a/.github/workflows/glossary-maintainer.md +++ b/.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 diff --git a/.github/workflows/shared/mcp/qmd-docs.md b/.github/workflows/shared/mcp/qmd-docs.md index 90a84e5f4b..a8d5457414 100644 --- a/.github/workflows/shared/mcp/qmd-docs.md +++ b/.github/workflows/shared/mcp/qmd-docs.md @@ -49,4 +49,16 @@ mcp-scripts: 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 diff --git a/.github/workflows/technical-doc-writer.md b/.github/workflows/technical-doc-writer.md index 86c4789829..3ec3962c4c 100644 --- a/.github/workflows/technical-doc-writer.md +++ b/.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 diff --git a/.github/workflows/unbloat-docs.md b/.github/workflows/unbloat-docs.md index 3f28c1d161..7f4f01a391 100644 --- a/.github/workflows/unbloat-docs.md +++ b/.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 ```