docs: make WorkIQ guidance grounding-first and host-neutral - #197
Open
Tolga Kilicli (tolgaki) wants to merge 24 commits into
Open
docs: make WorkIQ guidance grounding-first and host-neutral#197Tolga Kilicli (tolgaki) wants to merge 24 commits into
Tolga Kilicli (tolgaki) wants to merge 24 commits into
Conversation
Update the skill to the 0817 baseline combined with MCS metadata filtering optimizations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove contradictory completeness and retry guidance, make metadata enumeration host-neutral, and centralize the detailed workflow in its reference. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This reverts commit 2a642e9.
Make governed scope query-specific, clarify continuation paging, rehydrate traversal candidates, and separate absent columns from empty values. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: bb6cb03f-bae2-476f-9ba0-166be8383392
Replace MCS-specific KnowledgeSearch references with host-neutral SharePoint search wording. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Generalize indexing and rejected-path instructions and remove internal tracking identifiers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Avoid assuming a code interpreter is available and refer to host-provided code-writing or calculation tools instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace the version-specific reference with the named policy section and summarize the required stop behavior inline. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Document the validated two-hop drive and item addressing sequence, unsupported path forms, and bounded discovery fallback. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Treat retrieved M365 content as untrusted data, avoid replaying mutations with ambiguous outcomes, and prevent upload-session credentials from appearing in model output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Tolga Kilicli (tolgaki)
requested review from
Darrel (darrelmiller)
and
a lite review from Copilot
September 9, 2026 00:15
There was a problem hiding this comment.
🟡 Changes recommended
A few new/updated docs imply preview retrieve availability depends on installing workiq-preview, but availability is tenant-gated regardless of whether workiq or workiq-preview is installed.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates the WorkIQ skill and plugin documentation to distinguish caller-owned retrieval (preview retrieve) from Microsoft 365 Copilot-owned synthesis (ask), and documents strategy selection, capability restrictions, and tenant-dependent availability/fallback behavior.
Changes:
- Add end-to-end guidance for preview
retrieve(contract, strategies, capability constraints, response handling, and fallback when not tenant-enabled). - Update existing
askdocs and skill routing guidance to clearly separate “evidence gathering” vs “delegated answer.” - Refresh top-level plugin and repo catalogs (READMEs,
PLUGINS.md,AGENTS.md) to reflect the retrieve/ask/entity-tool split.
File summaries
| File | Description |
|---|---|
| plugins/workiq/skills/workiq/SKILL.md | Reframes skill guidance around retrieve vs ask, adds retrieve tool docs and grounding rules updates. |
| plugins/workiq/skills/workiq/references/troubleshooting.md | Adds retrieve-specific troubleshooting and availability notes. |
| plugins/workiq/skills/workiq/references/retrieve-work-iq.md | New reference documenting preview retrieve contract, strategy selection, and response handling. |
| plugins/workiq/skills/workiq/references/ask-work-iq.md | Updates ask reference to position it as Copilot-owned synthesis and define fallback when retrieve is unavailable. |
| plugins/workiq/README.md | Adds plugin-level usage docs for retrieve and clarifies tenant-dependent preview behavior. |
| plugins/workiq-preview/skills/workiq-preview/SKILL.md | Mirrors the same retrieve/ask/entity routing and tool docs in the preview skill. |
| plugins/workiq-preview/skills/workiq-preview/references/troubleshooting.md | Mirrors retrieve troubleshooting guidance for the preview skill. |
| plugins/workiq-preview/skills/workiq-preview/references/retrieve-work-iq.md | New preview retrieve reference (parallel to workiq). |
| plugins/workiq-preview/skills/workiq-preview/references/ask-work-iq.md | Mirrors ask doc updates for the preview skill. |
| plugins/workiq-preview/README.md | Mirrors plugin-level retrieve guidance for the preview plugin. |
| PLUGINS.md | Updates plugin directory descriptions and WorkIQ sections to reflect retrieve/ask/entity routing and availability caveats. |
| AGENTS.md | Updates repository context to reflect preview retrieve guidance and capability/strategy constraints. |
Review details
- Files reviewed: 12/12 changed files
- Comments generated: 4
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Tolga Kilicli (tolgaki)
added a commit
that referenced
this pull request
Sep 9, 2026
Preserve the preview retrieve guidance in AGENTS.md and PLUGINS.md while retaining main's removal of obsolete Work IQ EULA files and references. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Darrel (darrelmiller)
approved these changes
Sep 9, 2026
Distinguish caller-owned retrieval from Copilot synthesis, document source-based strategies and capability restrictions, and handle tenant-dependent availability and retrieval failures. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Tolga Kilicli (tolgaki)
force-pushed
the
tolgaki-microsoft-workiq-retrieve-guidance
branch
from
September 9, 2026 13:11
cb83476 to
a09c03d
Compare
Keep retrieve/ask evidence ownership and safeguards in concise skill front pages, preserve detailed workflows in references, and align draft, calendar, file, query, and mail-exchange guidance. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Tolga Kilicli (tolgaki)
changed the title
Clarified instructions for discovering Business Applications resources and emphasized the use of natural language queries.
[WorkIQ] Add Business Applications guidance
…ovement_0828 Improve WorkIQ skill with 0816 guidance and metadata filtering
Retain Business Applications, SharePoint library metadata, and newer mutation recovery guidance while adopting the compact entry skill. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Unify both WorkIQ skills around caller-owned retrieval, intentional agent delegation, canonical domain workflows, and operation-aware recovery. Preserve mainline SharePoint and Business Applications behavior. Add synthetic contracts, trace validation, package parity, and scoped CI checks without claiming live agent compliance. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Retain the inherited list-item to driveItem resolution chain in the canonical SharePoint reference, with explicit provenance and denial safeguards. Add a regression for using the wrong item identity in the download path. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Separate shared agent policy from host-specific installation and validation. Synchronize both marketplaces and GitHub, Claude, and Codex plugin manifests at 2.1.0, with a regression gate for matching public and preview versions. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Restore explicit M365 workload and action coverage in host metadata. Keep both current versions at 2.1.0 while allowing future public/preview divergence; validate each package against its own marketplace and host manifests. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Make omitted capability filters explicit for unspecified sources, preserve justified scoped retrieval, and require date-specific calendar offsets with timezone round-trip checks. Add focused source-filter and spring/fall DST regressions without changing the broader oracle policies or plugin versions. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Tolga Kilicli (tolgaki)
changed the title
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.
Summary
Extend the original retrieve/ask/entity routing work with shared workflow contracts, host-neutral discovery, and focused source-filter/timezone safeguards.
retrievewith explicit Grounding for caller-owned context, including unspecified locations. Reserveaskfor intentional Copilot or named-agent delegation.capabilitieswhen source families are unspecified rather than guessing a narrower allow-list. Preserve explicit restrictions and justified targeted source needs.Documentation and test-infrastructure changes only: no shipping MCP endpoint, server implementation, tenant permission, or authentication configuration changes. Installing a plugin does not enable tenant-gated tools.
Validation
npm --prefix tests/workiq-guidance test: 422 passing offline checks at7544b03.96af058; subsequent focused source-filter/timezone hardening is in7544b03.Static/synthetic checks and CLI loading are not live endpoint validation, answer-quality results, or certification of every agent host. The mock evaluation performed no live Microsoft 365 reads or writes. Private evaluation artifacts are not included.
Known validation follow-up
Broader synthetic-oracle repairs remain separate work: zero-call acceptance, two fixture/operation-contract mismatches, per-request retry tracking, and compound pending/denied outcomes. This PR does not claim complete conformance enforcement or that all release gates are satisfied. The latest commit addresses the two identified skill-level hardening items, not those broader oracle issues.