Skip to content

Add Sensei/frontmatter guardrails for trigger-overlap disambiguation regressions - #1778

Merged
kvenkatrajan merged 13 commits into
mainfrom
copilot/add-sensei-rule-for-disambiguation
Apr 9, 2026
Merged

Add Sensei/frontmatter guardrails for trigger-overlap disambiguation regressions#1778
kvenkatrajan merged 13 commits into
mainfrom
copilot/add-sensei-rule-for-disambiguation

Conversation

Copilot AI commented Apr 8, 2026

Copy link
Copy Markdown
Contributor

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

    • Trigger-overlap detection in scripts/src/frontmatter/cli.ts:
      • Parses WHEN:, USE FOR:, and TRIGGERS: phrases.
      • Identifies overlap between specialized skills and broad routing skills (notably azure-prepare / azure-deploy).
    • Disambiguation requirement error:
      • Emits trigger-overlap-disambiguation when overlap exists and the skill description lacks:
        • DO NOT USE FOR:, and
        • PREFER OVER <competing-skill>.
    • Regression error on clause removal:
      • Compares current skill description to base ref via git.
      • Emits disambiguation-removal when a prior DO NOT USE FOR or PREFER OVER clause is removed.
  • Validator/reporting updates

    • Adds new check keys to frontmatter JSON output:
      • trigger-overlap-disambiguation
      • disambiguation-removal
    • Treats both checks as errors to block high-risk routing regressions.
  • Documentation

    • Updates .github/skills/sensei/references/SCORING.md to define the new automated routing-regression guard behavior and error-level reporting.
  • Test coverage

    • Extends scripts/src/frontmatter/__tests__/frontmatter.test.ts for:
      • trigger phrase extraction
      • DO NOT USE FOR / PREFER OVER detection
      • overlap check behavior and severity
      • disambiguation-removal behavior and severity
// Example issue emitted by the new rule
{
  check: "trigger-overlap-disambiguation",
  severity: "error",
  message: 'Trigger overlap with broad skill "azure-prepare" (...). Add DO NOT USE FOR: or PREFER OVER azure-prepare.'
}

Copilot AI changed the title [WIP] Add sensei rule to detect missing disambiguation for competing skills Add Sensei/frontmatter guardrails for trigger-overlap disambiguation regressions Apr 8, 2026
Copilot AI requested a review from kvenkatrajan April 8, 2026 22:48

@kvenkatrajan kvenkatrajan left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review — PR #1778: Add Disambiguation Overlap and Removal Warnings

✅ Strengths

  1. Clean separation of concerns — Each function (extractTriggerPhrases, hasDoNotUseForClause, hasPreferOverClause, isDisambiguationClauseRemoved) is small, single-purpose, and independently testable.
  2. Defensive regex stop-boundariesTRIGGER_SECTION_RE explicitly stops before DO NOT USE FOR / PREFER OVER sections, preventing anti-triggers from being parsed as positive triggers.
  3. Robust base-ref fallbackgetMergeBaseRef() tries origin/main, origin/master, local main/master, then HEAD~1 — handles CI, forks, and shallow clones gracefully.
  4. Warning-only severity — New checks are warnings, not errors. Avoids blocking unrelated skill PRs while surfacing routing risk.
  5. 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.

@kvenkatrajan

Copy link
Copy Markdown
Collaborator

Copilot fix the medium and low findings

Comment thread scripts/src/frontmatter/cli.ts Outdated
Comment thread scripts/src/frontmatter/cli.ts Outdated
Comment thread scripts/src/frontmatter/cli.ts Outdated
Comment thread scripts/src/frontmatter/cli.ts Outdated
Comment thread scripts/src/frontmatter/__tests__/frontmatter.test.ts

Copilot AI commented Apr 8, 2026

Copy link
Copy Markdown
Contributor Author

Copilot fix the medium and low findings

Implemented the medium and low findings in commit f177722: broad-skill detection is now explicit allowlist-only, regex cache was removed, anti-trigger stop-boundary behavior is covered by test, and disambiguation-removal warning text is now more actionable/grammatical.

Copilot AI requested a review from kvenkatrajan April 8, 2026 23:45
@kvenkatrajan
kvenkatrajan marked this pull request as ready for review April 8, 2026 23:59
Copilot AI review requested due to automatic review settings April 8, 2026 23:59

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-disambiguation warning when specialized skills overlap broad routing skills without DO NOT USE FOR: or PREFER OVER <skill>.
  • Added disambiguation-removal warning 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

Comment thread scripts/src/frontmatter/cli.ts Outdated
Comment thread scripts/src/frontmatter/cli.ts
Comment thread scripts/src/frontmatter/cli.ts
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings April 9, 2026 00:12
@github-actions

github-actions Bot commented Apr 9, 2026

Copy link
Copy Markdown
Contributor
Details# 🔍 Token Analysis Report

@github-copilot-for-azure/scripts@1.0.0 tokens
node --import tsx src/tokens/cli.ts compare --base origin/main --head HEAD --markdown

📊 Token Change Report

Comparing origin/mainHEAD

Summary

Metric Value
📈 Total Change +96 tokens (+2%)
Before 4,200 tokens
After 4,296 tokens
Files Changed 1

Changed Files

File Before After Change
.github/skills/sensei/references/SCORING.md 4,200 4,296 +96 (+2%)

@github-copilot-for-azure/scripts@1.0.0 tokens
node --import tsx src/tokens/cli.ts check --markdown

📊 Token Limit Check Report

Checked: 546 files
Exceeded: 76 files

⚠️ Files Exceeding Token Limits

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.

@kvenkatrajan

Copy link
Copy Markdown
Collaborator

Copilot - Bump sensei skill version

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 a trigger-overlap-disambiguation warning when disambiguation is missing.
  • Add a git-based regression check that warns (disambiguation-removal) when an existing DO NOT USE FOR: / PREFER OVER disambiguation 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

Copilot AI commented Apr 9, 2026

Copy link
Copy Markdown
Contributor Author

Copilot - Bump sensei skill version

Done in commit e3d4374: bumped .github/skills/sensei/SKILL.md metadata.version from 1.0.3 to 1.0.4.

Comment thread scripts/src/frontmatter/cli.ts Outdated
Comment thread scripts/src/frontmatter/cli.ts Outdated
Comment thread .github/skills/sensei/references/SCORING.md Outdated
Copilot AI review requested due to automatic review settings April 9, 2026 00:36
Copilot AI removed the request for review from Copilot April 9, 2026 00:36
Copilot AI requested review from Copilot and removed request for Copilot April 9, 2026 00:40

Copilot AI commented Apr 9, 2026

Copy link
Copy Markdown
Contributor Author

Copilot fix the medium and low findings

Addressed in commit f177722 (medium/low findings) and followed up in a479e8b for error-level severities.

Copilot - Bump sensei skill version

Done in commit 19210c6: bumped .github/skills/sensei/SKILL.md metadata.version to 1.0.5.

@kvenkatrajan
kvenkatrajan merged commit b342c82 into main Apr 9, 2026
9 checks passed
@kvenkatrajan
kvenkatrajan deleted the copilot/add-sensei-rule-for-disambiguation branch April 9, 2026 13:12
Barbara 4bes (Ba4bes) pushed a commit to Ba4bes/GitHub-Copilot-for-Azure that referenced this pull request Apr 24, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add sensei rule to detect missing disambiguation for competing skills

5 participants