Add Sensei/frontmatter guardrails for trigger-overlap disambiguation regressions - #1778
Conversation
Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
…llback Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
…ion helper Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
…pers Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
kvenkatrajan
left a comment
There was a problem hiding this comment.
Code Review — PR #1778: Add Disambiguation Overlap and Removal Warnings
✅ Strengths
- Clean separation of concerns — Each function (
extractTriggerPhrases,hasDoNotUseForClause,hasPreferOverClause,isDisambiguationClauseRemoved) is small, single-purpose, and independently testable. - Defensive regex stop-boundaries —
TRIGGER_SECTION_REexplicitly stops beforeDO NOT USE FOR/PREFER OVERsections, preventing anti-triggers from being parsed as positive triggers. - Robust base-ref fallback —
getMergeBaseRef()triesorigin/main,origin/master, localmain/master, thenHEAD~1— handles CI, forks, and shallow clones gracefully. - Warning-only severity — New checks are warnings, not errors. Avoids blocking unrelated skill PRs while surfacing routing risk.
- Good test coverage — 7 unit tests covering extraction, detection, overlap warnings, disambiguation, and the null-previous edge case.
🟡 Medium Findings
1. Hardcoded BROAD_TRIGGER_PHRASES will drift out of sync (cli.ts)
The static list of 10 phrases will silently go stale as azure-prepare/azure-deploy evolve. New broad triggers won't be detected, removed ones cause false positives.
→ Derive dynamically from actual broad skill descriptions, or add a test asserting this set is a subset of extracted triggers from broad skills.
2. PREFER_OVER_REGEX_CACHE is a module-level Map that grows without bound (cli.ts)
Each unique competingSkillName adds a compiled RegExp. Tests in the same process may see cross-test pollution.
→ Clear cache at the start of each main() run, or just inline new RegExp(...) since skill count is small.
3. No test for extractTriggerPhrases stopping before DO NOT USE FOR (frontmatter.test.ts)
The regex stop-boundary is a key correctness property but no test verifies it.
→ Add: "WHEN: deploy to Azure. DO NOT USE FOR: generic apps" should extract only "deploy to azure", not "generic apps".
4. isBroadRoutingSkill threshold could classify unexpected skills as broad (cli.ts)
Any skill with ≥2 matches in BROAD_TRIGGER_PHRASES is classified broad, skipping overlap checks even if specialized.
→ Consider relying solely on the BROAD_SKILL_NAMES allowlist. If keeping the threshold, add a test for the edge case.
🟢 Low Findings
5. Alignment inconsistency (cli.ts line 548) — Extra leading space on check: property.
6. buildDisambiguationRemovalIssues message could be more actionable (cli.ts) — Doesn't say which clause was removed or which competing skill it disambiguated. Including that context helps PR authors fix faster.
Summary
| Severity | Count |
|---|---|
| 🔴 Critical | 0 |
| 🟠 High | 0 |
| 🟡 Medium | 4 |
| 🟢 Low | 2 |
Overall Assessment: Comment — Solid, well-structured PR. Medium findings are about long-term maintainability, not immediate correctness. No blockers.
|
Copilot fix the medium and low findings |
Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/5c8e4583-3f4b-478a-bdf2-7c89bdfe41f0 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/5c8e4583-3f4b-478a-bdf2-7c89bdfe41f0 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
…e grammar Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/5c8e4583-3f4b-478a-bdf2-7c89bdfe41f0 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
Implemented the medium and low findings in commit |
There was a problem hiding this comment.
Pull request overview
Adds new Sensei/frontmatter guardrails to detect skill-routing regressions caused by ambiguous trigger overlap and removal of explicit disambiguation clauses.
Changes:
- Added trigger phrase extraction + overlap detection to emit a
trigger-overlap-disambiguationwarning when specialized skills overlap broad routing skills withoutDO NOT USE FOR:orPREFER OVER <skill>. - Added
disambiguation-removalwarning by comparing current skill descriptions to a git merge-base to detect removal of prior disambiguation clauses. - Updated Sensei scoring reference docs and expanded frontmatter validator tests for the new helpers/rules.
Show a summary per file
| File | Description |
|---|---|
| scripts/src/frontmatter/cli.ts | Implements trigger phrase parsing, overlap/disambiguation warnings, git-based regression detection, and adds new check keys to JSON output. |
| scripts/src/frontmatter/tests/frontmatter.test.ts | Adds unit tests for phrase extraction and the new warning behaviors. |
| .github/skills/sensei/references/SCORING.md | Documents the new automated routing-regression guard behavior. |
Copilot's findings
- Files reviewed: 3/3 changed files
- Comments generated: 3
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Details# 🔍 Token Analysis Report
📊 Token Change ReportComparing Summary
Changed Files
📊 Token Limit Check ReportChecked: 546 files
|
| File | Tokens | Limit | Over By |
|---|---|---|---|
.github/skills/analyze-test-run/SKILL.md |
2471 | 500 | +1971 |
.github/skills/file-test-bug/SKILL.md |
628 | 500 | +128 |
.github/skills/sensei/README.md |
3531 | 2000 | +1531 |
.github/skills/sensei/SKILL.md |
3026 | 500 | +2526 |
.github/skills/sensei/references/EXAMPLES.md |
3701 | 2000 | +1701 |
.github/skills/sensei/references/LOOP.md |
4181 | 2000 | +2181 |
.github/skills/sensei/references/SCORING.md |
4296 | 2000 | +2296 |
.github/skills/skill-authoring/SKILL.md |
839 | 500 | +339 |
plugin/skills/appinsights-instrumentation/SKILL.md |
908 | 500 | +408 |
plugin/skills/azure-ai/SKILL.md |
817 | 500 | +317 |
plugin/skills/azure-aigateway/SKILL.md |
1258 | 500 | +758 |
plugin/skills/azure-aigateway/references/policies.md |
2342 | 2000 | +342 |
plugin/skills/azure-cloud-migrate/SKILL.md |
559 | 500 | +59 |
plugin/skills/azure-cloud-migrate/references/services/container-apps/cloudrun-deployment-guide.md |
2029 | 2000 | +29 |
plugin/skills/azure-cloud-migrate/references/services/functions/lambda-to-functions.md |
2600 | 2000 | +600 |
plugin/skills/azure-cloud-migrate/references/services/functions/runtimes/javascript.md |
2181 | 2000 | +181 |
plugin/skills/azure-compliance/SKILL.md |
1185 | 500 | +685 |
plugin/skills/azure-compute/SKILL.md |
755 | 500 | +255 |
plugin/skills/azure-compute/workflows/vm-recommender/vm-recommender.md |
2393 | 2000 | +393 |
plugin/skills/azure-cost/SKILL.md |
1861 | 500 | +1361 |
plugin/skills/azure-deploy/SKILL.md |
1643 | 500 | +1143 |
plugin/skills/azure-deploy/references/pre-deploy-checklist.md |
3224 | 2000 | +1224 |
plugin/skills/azure-deploy/references/recipes/azd/errors.md |
3452 | 2000 | +1452 |
plugin/skills/azure-deploy/references/troubleshooting.md |
2038 | 2000 | +38 |
plugin/skills/azure-diagnostics/SKILL.md |
1132 | 500 | +632 |
plugin/skills/azure-diagnostics/aks-troubleshooting/networking.md |
2147 | 2000 | +147 |
plugin/skills/azure-diagnostics/aks-troubleshooting/node-issues.md |
2003 | 2000 | +3 |
plugin/skills/azure-enterprise-infra-planner/SKILL.md |
999 | 500 | +499 |
plugin/skills/azure-enterprise-infra-planner/references/constraints/compute-apps.md |
2022 | 2000 | +22 |
plugin/skills/azure-hosted-copilot-sdk/SKILL.md |
1260 | 500 | +760 |
plugin/skills/azure-kubernetes/SKILL.md |
2266 | 500 | +1766 |
plugin/skills/azure-kusto/SKILL.md |
2149 | 500 | +1649 |
plugin/skills/azure-messaging/SKILL.md |
967 | 500 | +467 |
plugin/skills/azure-prepare/SKILL.md |
3110 | 500 | +2610 |
plugin/skills/azure-prepare/references/aspire.md |
4003 | 2000 | +2003 |
plugin/skills/azure-prepare/references/plan-template.md |
2559 | 2000 | +559 |
plugin/skills/azure-prepare/references/recipes/azd/aspire.md |
3069 | 2000 | +1069 |
plugin/skills/azure-prepare/references/recipes/azd/terraform.md |
3012 | 2000 | +1012 |
plugin/skills/azure-prepare/references/research.md |
2217 | 2000 | +217 |
plugin/skills/azure-prepare/references/resources-limits-quotas.md |
3322 | 2000 | +1322 |
plugin/skills/azure-prepare/references/security.md |
2147 | 2000 | +147 |
plugin/skills/azure-prepare/references/services/functions/bicep.md |
3065 | 2000 | +1065 |
plugin/skills/azure-prepare/references/services/functions/templates/SPEC-composable-templates.md |
6187 | 2000 | +4187 |
plugin/skills/azure-prepare/references/services/functions/templates/recipes/composition.md |
4649 | 2000 | +2649 |
plugin/skills/azure-prepare/references/services/functions/terraform.md |
3358 | 2000 | +1358 |
plugin/skills/azure-quotas/SKILL.md |
3445 | 500 | +2945 |
plugin/skills/azure-quotas/references/commands.md |
2644 | 2000 | +644 |
plugin/skills/azure-resource-lookup/SKILL.md |
1288 | 500 | +788 |
plugin/skills/azure-resource-visualizer/SKILL.md |
2054 | 500 | +1554 |
plugin/skills/azure-storage/SKILL.md |
1180 | 500 | +680 |
plugin/skills/azure-upgrade/SKILL.md |
1001 | 500 | +501 |
plugin/skills/azure-upgrade/references/services/functions/automation.md |
3463 | 2000 | +1463 |
plugin/skills/azure-upgrade/references/services/functions/consumption-to-flex.md |
2773 | 2000 | +773 |
plugin/skills/azure-validate/SKILL.md |
906 | 500 | +406 |
plugin/skills/entra-app-registration/SKILL.md |
2067 | 500 | +1567 |
plugin/skills/entra-app-registration/references/api-permissions.md |
2545 | 2000 | +545 |
plugin/skills/entra-app-registration/references/cli-commands.md |
2211 | 2000 | +211 |
plugin/skills/entra-app-registration/references/console-app-example.md |
2752 | 2000 | +752 |
plugin/skills/entra-app-registration/references/oauth-flows.md |
2375 | 2000 | +375 |
plugin/skills/microsoft-foundry/SKILL.md |
2870 | 500 | +2370 |
plugin/skills/microsoft-foundry/foundry-agent/create/create.md |
3016 | 2000 | +1016 |
plugin/skills/microsoft-foundry/foundry-agent/deploy/deploy.md |
5555 | 2000 | +3555 |
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/eval-datasets.md |
2342 | 2000 | +342 |
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/references/trace-to-dataset.md |
4268 | 2000 | +2268 |
plugin/skills/microsoft-foundry/foundry-agent/observe/observe.md |
2547 | 2000 | +547 |
plugin/skills/microsoft-foundry/foundry-agent/trace/references/kql-templates.md |
2701 | 2000 | +701 |
plugin/skills/microsoft-foundry/foundry-agent/troubleshoot/troubleshoot.md |
2164 | 2000 | +164 |
plugin/skills/microsoft-foundry/models/deploy-model/SKILL.md |
1640 | 500 | +1140 |
plugin/skills/microsoft-foundry/models/deploy-model/capacity/SKILL.md |
1739 | 500 | +1239 |
plugin/skills/microsoft-foundry/models/deploy-model/customize/SKILL.md |
2235 | 500 | +1735 |
plugin/skills/microsoft-foundry/models/deploy-model/customize/references/customize-workflow.md |
3335 | 2000 | +1335 |
plugin/skills/microsoft-foundry/models/deploy-model/preset/SKILL.md |
1226 | 500 | +726 |
plugin/skills/microsoft-foundry/models/deploy-model/preset/references/preset-workflow.md |
5534 | 2000 | +3534 |
plugin/skills/microsoft-foundry/quota/quota.md |
2288 | 2000 | +288 |
plugin/skills/microsoft-foundry/quota/references/capacity-planning.md |
2080 | 2000 | +80 |
plugin/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md |
2162 | 2000 | +162 |
Consider moving content to
references/subdirectories.
Automated token analysis. See skill authoring guidelines for best practices.
|
Copilot - Bump sensei skill version |
There was a problem hiding this comment.
Pull request overview
Adds new Sensei/frontmatter validator guardrails to detect likely routing regressions when skills overlap on trigger phrases but lack (or remove) explicit disambiguation clauses, helping keep skill routing stable as descriptions evolve.
Changes:
- Implement trigger-phrase extraction and overlap detection vs broad routing skills (e.g.,
azure-prepare,azure-deploy) and emit atrigger-overlap-disambiguationwarning when disambiguation is missing. - Add a git-based regression check that warns (
disambiguation-removal) when an existingDO NOT USE FOR:/PREFER OVERdisambiguation clause is removed relative to merge-base. - Extend frontmatter tests and update Sensei scoring documentation to define the new automated guard behavior.
Show a summary per file
| File | Description |
|---|---|
| scripts/src/frontmatter/cli.ts | Adds routing-context construction, trigger extraction, overlap/disambiguation warnings, and merge-base comparison for clause removal; surfaces results via existing JSON/reporting pipeline. |
| scripts/src/frontmatter/tests/frontmatter.test.ts | Adds unit tests for trigger phrase extraction, disambiguation clause detection, overlap warning emission, and disambiguation-removal warnings. |
| .github/skills/sensei/references/SCORING.md | Documents the new automated routing-regression guard behavior and when warnings are expected. |
Copilot's findings
- Files reviewed: 3/3 changed files
- Comments generated: 0 new
Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/5d35373d-e028-4778-9e84-93ec228e5f7f Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
Done in commit |
Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/4d75610f-518b-4c75-bb11-ca68ed50554a Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/addddfdd-40f6-4dd3-be59-f9461cc6a350 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com>
…regressions (microsoft#1778) * Initial plan * feat(frontmatter): add disambiguation overlap and removal warnings Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * chore(frontmatter): refine overlap rule readability and warning output Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * chore(frontmatter): extract overlap constants and improve base-ref fallback Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * chore(frontmatter): document routing heuristics and reuse disambiguation helper Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * test(frontmatter): cover disambiguation issue builder and cleanup helpers Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/358d7cbd-7cd3-4ab4-8852-7321bc4dc553 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * fix(frontmatter): address review findings for disambiguation checks Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/5c8e4583-3f4b-478a-bdf2-7c89bdfe41f0 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * chore(frontmatter): polish regex marker and warning wording Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/5c8e4583-3f4b-478a-bdf2-7c89bdfe41f0 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * chore(frontmatter): tighten disambiguation marker constant and message grammar Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/5c8e4583-3f4b-478a-bdf2-7c89bdfe41f0 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * Update scripts/src/frontmatter/cli.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * chore(sensei): bump metadata.version to 1.0.4 Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/5d35373d-e028-4778-9e84-93ec228e5f7f Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * fix(frontmatter): escalate disambiguation overlap/removal to errors Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/4d75610f-518b-4c75-bb11-ca68ed50554a Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> * chore(sensei): bump metadata.version to 1.0.5 Agent-Logs-Url: https://github.com/microsoft/GitHub-Copilot-for-Azure/sessions/addddfdd-40f6-4dd3-be59-f9461cc6a350 Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: kvenkatrajan <102772054+kvenkatrajan@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Routing regressions can occur when overlapping skills lose explicit disambiguation (
DO NOT USE FOR/PREFER OVER). This change adds an automated Sensei/frontmatter check to detect overlap-driven ambiguity and flag risky clause removals in PRs.What this adds
scripts/src/frontmatter/cli.ts:WHEN:,USE FOR:, andTRIGGERS:phrases.azure-prepare/azure-deploy).trigger-overlap-disambiguationwhen overlap exists and the skill description lacks:DO NOT USE FOR:, andPREFER OVER <competing-skill>.disambiguation-removalwhen a priorDO NOT USE FORorPREFER OVERclause is removed.Validator/reporting updates
trigger-overlap-disambiguationdisambiguation-removalDocumentation
.github/skills/sensei/references/SCORING.mdto define the new automated routing-regression guard behavior and error-level reporting.Test coverage
scripts/src/frontmatter/__tests__/frontmatter.test.tsfor:DO NOT USE FOR/PREFER OVERdetection