Conversation
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Update agentic workflows for qmd-docs import
Optimize qmd-docs workflows: explicitly instruct models to use qmd-query for doc search
Mar 14, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Updates several documentation-focused workflow instruction files to prefer qmd-query (semantic search) as the first step when locating relevant docs, before falling back to manual file listing.
Changes:
- Added
qmd-query-first guidance to multiple doc maintenance workflows (unbloat, technical writer, daily updater/healer, glossary, dictation). - Expanded the shared QMD guidance with “use it first” rules and query tips.
- Added examples of targeted
qmd-queryusage across workflows to narrow search scope earlier.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| .github/workflows/unbloat-docs.md | Adds a qmd-query-first step before scanning docs with find. |
| .github/workflows/technical-doc-writer.md | Adds qmd-query guidance to locate topic-relevant documentation earlier. |
| .github/workflows/shared/mcp/qmd-docs.md | Expands shared documentation on when/how to use qmd-query. |
| .github/workflows/glossary-maintainer.md | Adds guidance to use qmd-query for authoritative context per term. |
| .github/workflows/dictation-prompt.md | Adds qmd-query examples to sample broad areas of docs for vocabulary extraction. |
| .github/workflows/developer-docs-consolidator.md | Adds qmd-query guidance prior to listing markdown files. |
| .github/workflows/daily-doc-updater.md | Adds qmd-query-first guidance for searching existing docs for changes. |
| .github/workflows/daily-doc-healer.md | Adds qmd-query guidance for finding relevant docs when validating issues. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Comment on lines
+106
to
+113
| 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 | ||
| ``` |
Comment on lines
51
to
+58
| 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 | ||
|
|
Comment on lines
+60
to
+63
| - 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
All 7 workflows importing
shared/mcp/qmd-docs.mdhad theqmd-queryvector search tool available but never told the model to use it — so models defaulted to slower, less precisefind/bashfile listing instead of semantic search.Changes
shared/mcp/qmd-docs.mdExpanded the
<qmd>section from a single vague sentence into actionable guidance:find/bash, before writing new content, when discovering relevant files or understanding a conceptmin_scoretuning, always reading returned paths, combining targeted queriesPer-workflow prompt updates
Each workflow gets a targeted addition at the relevant decision point:
qmd-queryaddedtechnical-doc-writer.mddeveloper-docs-consolidator.mdfind specs -name '*.md'unbloat-docs.mddaily-doc-updater.mdfindglossary-maintainer.mddaily-doc-healer.mddictation-prompt.mdExample of the updated
qmd-docs.md<qmd>block:Warning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
https://api.github.com/graphql/usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw(http block)/usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw dex_baseline.md(http block)/usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw fixtures/basic-c-c fixtures/with-imgit status --porcelain --ignore-submodules | head -n 10 fixtures/smoke-copilot.md fixt�� fixtures/shared/github-mcp-app.md onsolidator.md 64/bin/git(http block)https://api.github.com/repos/actions/checkout/git/ref/tags/v3/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v3 --jq .object.sha -bool l /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/compile -errorsas -ifaceassert -nilfunc /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/compile -o /tmp/go-build3349656675/b383/_pkg_.a(http block)https://api.github.com/repos/actions/checkout/git/ref/tags/v5/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq .object.sha -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json GO111MODULE 64/pkg/tool/linux_amd64/compile GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/compile(http block)https://api.github.com/repos/actions/checkout/git/ref/tags/v6/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq .object.sha --show-toplevel _9a60CKVjggF /opt/hostedtoolcache/node/24.14.0/x64/bin/node /tmp/go-build399git -trimpath 64/bin/go node /tmp�� /tmp/TestHashConsistency_KeyOrdering995963773/001/test1.md go /opt/hostedtoolcache/node/24.14.0/x64/bin/node -json GO111MODULE x_amd64/vet node(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq .object.sha user.email test@example.com ache/node/24.14.0/x64/bin/node /tmp/go-build399git -trimpath 64/bin/go ache/node/24.14.0/x64/bin/node 1145�� --show-toplevel go /usr/bin/git -json GO111MODULE x_amd64/vet git(http block)https://api.github.com/repos/actions/github-script/git/ref/tags/v8/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq .object.sha run lint:cjs 64/bin/go GOSUMDB GOWORK 64/bin/go sh -c "prettier" --check 'scripts/**/*GOINSECURE sh 64/bin/go "prettier" --wri/opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq .object.sha che/go-build/ec/ec592ac3a4cb56bfGOINSECURE GOPROXY 64/bin/go GOSUMDB GOWORK run-script/lib/n-unreachable=false /opt/hostedtoolc/tmp/go-build3349656675/b228/vet.cfg -o /tmp/go-build3994714152/b410/_pkGOINSECURE -trimpath 64/bin/go -p github.com/githu-atomic -lang=go1.25 go(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq .object.sha che/go-build/5a/5a8a5bbe22444b35GOINSECURE **/*.cjs 64/bin/go **/*.json --ignore-path ../../../.pretti-unreachable=false /opt/hostedtoolc/tmp/go-build3349656675/b264/vet.cfg -o /tmp/go-build3994714152/b394/_pkGOINSECURE -trimpath 64/bin/go -p github.com/githu-atomic -lang=go1.25 go(http block)https://api.github.com/repos/actions/setup-go/git/ref/tags/v4/usr/bin/gh gh api /repos/actions/setup-go/git/ref/tags/v4 --jq .object.sha --show-toplevel /opt/hostedtoolc/tmp/go-build3349656675/b261/vet.cfg ache/node/24.14.0/x64/bin/node /tmp/go-build399git -trimpath 64/bin/go ache/node/24.14.0/x64/bin/node 6046��(http block)https://api.github.com/repos/actions/setup-node/git/ref/tags/v4/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v4 --jq .object.sha --show-toplevel /tmp/go-build3349656675/b392/_testmain.go ache/node/24.14.0/x64/bin/node /tmp/go-build399git -trimpath 64/bin/go ache/node/24.14.0/x64/bin/node 7539�� uts.version go /usr/bin/git -json GO111MODULE x_amd64/vet git(http block)https://api.github.com/repos/actions/upload-artifact/git/ref/tags/v4/usr/bin/gh gh api /repos/actions/upload-artifact/git/ref/tags/v4 --jq .object.sha /tmp/go-build3349656675/b370/_pkg_.a -trimpath 9656675/b327/vet.cfg -p main -lang=go1.25 /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -uns�� -unreachable=false resolved$ ache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -c=4 -nolocalimports -importcfg ache/go/1.25.0/x64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b/usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq .object.sha(http block)https://api.github.com/repos/github/gh-aw/usr/bin/gh gh api /repos/github/gh-aw --jq .visibility(http block)https://api.github.com/repos/github/gh-aw-actions/git/ref/tags/v1.0.0/usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v1.0.0 --jq .object.sha runs/20260314-212335-29798/test-907623399/.github/workflows /tmp/go-build3349656675/b042/vet.cfg 9656675/b330/vet.cfg GOSUMDB GOWORK 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linuremote.origin.url -uns�� -unreachable=false /tmp/go-build3349656675/b223/vet.cfg /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -json 9ce8485ddb0bfc39rev-parse 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linu2(http block)https://api.github.com/repos/github/gh-aw-actions/git/ref/tags/v1.2.3/usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v1.2.3 --jq .object.sha runs/20260314-212335-29798/test-907623399/.github/workflows /tmp/go-build3349656675/b036/vet.cfg g_.a GOSUMDB GOWORK 64/bin/go yp/R17li3uygAJmV_QUkyJ3/kboiTJnM-P3JqtOie1CV -uns�� -unreachable=false /tmp/go-build3349656675/b220/vet.cfg /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -json GO111MODULE 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linu^remote\..*\.gh-resolved$(http block)https://api.github.com/repos/github/gh-aw/actions/runs/1/artifacts/usr/bin/gh gh run download 1 --dir test-logs/run-1 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/actions/runs/12345/artifacts/usr/bin/gh gh run download 12345 --dir test-logs/run-12345 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linutest@example.com(http block)https://api.github.com/repos/github/gh-aw/actions/runs/12346/artifacts/usr/bin/gh gh run download 12346 --dir test-logs/run-12346 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/actions/runs/2/artifacts/usr/bin/gh gh run download 2 --dir test-logs/run-2 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linuTest User env 907623399/.github/workflows .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/actions/runs/3/artifacts/usr/bin/gh gh run download 3 --dir test-logs/run-3 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json .cfg x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/actions/runs/4/artifacts/usr/bin/gh gh run download 4 --dir test-logs/run-4 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linutest@example.com env 907623399/.github/workflows .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/actions/runs/5/artifacts/usr/bin/gh gh run download 5 --dir test-logs/run-5 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env 907623399/.github/workflows .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/actions/workflows/usr/bin/gh gh workflow list --json name,state,path npx prettier --c-errorsas GOPROXY 64/bin/go GOSUMDB GOWORK 64/bin/go node /hom�� --check scripts/**/*.js 64/bin/go .prettierignore ../../../pkg/wor-atomic 64/bin/go go(http block)/usr/bin/gh gh run list --json databaseId,number,url,status,conclusion,workflowName,createdAt,startedAt,updatedAt,event,headBranch,headSha,displayTitle --workflow nonexistent-workflow-12345 --limit 100 /tmp/go-build3349656675/b416/importcfg -pack /tmp/go-build3349656675/b416/_testmain.go env -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go(http block)/usr/bin/gh gh run list --json databaseId,number,url,status,conclusion,workflowName,createdAt,startedAt,updatedAt,event,headBranch,headSha,displayTitle --workflow nonexistent-workflow-12345 --limit 6 GOMOD GOMODCACHE x_amd64/compile env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb --jq .object.sha(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/v1.0.0/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v1.0.0 --jq .object.sha -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json GO111MODULE x_amd64/compile GOINSECURE GOMOD GOMODCACHE x_amd64/compile(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/v1.2.3/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v1.2.3 --jq .object.sha /tmp/go-build3994714152/b358/_pkGOINSECURE -trimpath 64/bin/go -d github.com/githu-atomic -lang=go1.25 go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/v2.0.0/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq .object.sha -x c 64/bin/go -(http block)/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq .object.sha /tmp/go-build3994714152/b392/_pkGOINSECURE -trimpath 64/bin/go -p github.com/githu-atomic -lang=go1.25 go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet(http block)/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq .object.sha /tmp/go-build3994714152/b387/_pkGOINSECURE -trimpath 64/bin/go -p github.com/charm-atomic -lang=go1.24 go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/v3.0.0/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v3.0.0 --jq .object.sha /tmp/go-build3994714152/b377/_pkGOINSECURE -trimpath 64/bin/go -p github.com/pmeza-atomic -lang=go1.16 go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet(http block)https://api.github.com/repos/githubnext/agentics/git/ref/tags//usr/bin/gh gh api /repos/githubnext/agentics/git/ref/tags/# --jq .object.sha(http block)https://api.github.com/repos/nonexistent/action/git/ref/tags/v999.999.999/usr/bin/gh gh api /repos/nonexistent/action/git/ref/tags/v999.999.999 --jq .object.sha -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/nonexistent/repo/actions/runs/12345/usr/bin/gh gh run view 12345 --repo nonexistent/repo --json status,conclusion GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/owner/repo/actions/workflows/usr/bin/gh gh workflow list --json name,state,path --repo owner/repo 64/bin/go **/*.ts **/*.json --ignore-path node /hom�� --check scripts/**/*.js 64/bin/go .prettierignore ../../../pkg/wor-atomic 64/bin/go go(http block)/usr/bin/gh gh workflow list --json name,state,path --repo owner/repo 64/bin/go **/*.ts **/*.json --ignore-path /bin/sh -c echo "��� JavaSc-c=4 node 64/bin/go /golden.go ../../../pkg/wor-atomic 64/bin/go go(http block)https://api.github.com/repos/owner/repo/contents/file.md/tmp/go-build3349656675/b383/cli.test /tmp/go-build3349656675/b383/cli.test -test.testlogfile=/tmp/go-build3349656675/b383/testlog.txt -test.paniconexit0 -test.v=true -test.parallel=4 -test.timeout=10m0s -test.run=^Test -test.short=true GOINSECURE GOMOD GOMODCACHE 4714152/b384/imp-buildtags /hom�� che/go-build/34/-errorsas **/*.cjs 64/bin/go **/*.json --ignore-path ../../../.pretti-unreachable=false /opt/hostedtoolc/tmp/go-build3349656675/b263/vet.cfg(http block)https://api.github.com/repos/test-owner/test-repo/actions/secrets/usr/bin/gh gh api /repos/test-owner/test-repo/actions/secrets --jq .secrets[].name npx prettier --c-errorsas GOPROXY 64/bin/go GOSUMDB GOWORK 64/bin/go sh -c "prettier" --che-errorsas node 64/bin/go tierignore ../../../pkg/wor-atomic 64/bin/go go(http block)If you need me to access, download, or install something from one of these locations, you can either:
Original prompt
💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.