Commit 26a32ea
feat(skills): enhance pr-reference skill with flexible filtering and base branch detection (#1095)
Enhanced the `pr-reference` skill with four new capabilities: automatic
default branch detection, merge-base comparison, multi-type file
filtering, and extension/path exclusion. All changes are mirrored across
bash and PowerShell implementations with comprehensive Pester test
coverage (95.9% line coverage for the package).
### Changes
**`generate.sh` / `generate.ps1`:**
- Added `--merge-base` / `-MergeBase` flag for three-way comparison via
`git merge-base` instead of direct diff
- Added `--base-branch auto` / `-BaseBranch auto` to detect the remote
default branch via `git symbolic-ref refs/remotes/origin/HEAD` with
`origin/main` fallback
- Added `--exclude-ext` / `-ExcludeExt` for comma-separated file
extension exclusion from diffs using git pathspec negation
- Added `--exclude-path` / `-ExcludePath` for comma-separated path
prefix exclusion from diffs
**`list-changed-files.sh` / `list-changed-files.ps1`:**
- Support comma-separated `--type` / `-Type` values (e.g., `--type
added,modified,renamed`)
- Added `--exclude-type` / `-ExcludeType` for inverse type filtering
with mutual exclusion validation
**`shared.psm1`:**
- Added `Resolve-DefaultBranch` helper for auto-detecting the remote
default branch
- Added `Build-PathspecExclusions` helper for constructing git pathspec
negation arrays from extensions and paths
**`SKILL.md`:**
- Updated Parameters Reference table with all new flags for both
generate and list-changed-files scripts
- Updated usage examples showing new capabilities
**Pester Tests:**
- Added test contexts for `-MergeBase`, `-BaseBranch auto`,
`-ExcludeExt`, `-ExcludePath`, combined flags
- Added test contexts for comma-separated `-Type`, `-ExcludeType`,
mutual exclusion, invalid type validation
- Added test contexts for `Resolve-DefaultBranch` (success + fallback)
and `Build-PathspecExclusions` (extensions, paths, combined, edge cases)
## Related Issue(s)
Closes #1011
## Type of Change
Select all that apply:
**Code & Documentation:**
* [ ] Bug fix (non-breaking change fixing an issue)
* [x] New feature (non-breaking change adding functionality)
* [ ] Breaking change (fix or feature causing existing functionality to
change)
* [x] Documentation update
**Infrastructure & Configuration:**
* [ ] GitHub Actions workflow
* [ ] Linting configuration (markdown, PowerShell, etc.)
* [ ] Security configuration
* [ ] DevContainer configuration
* [ ] Dependency update
**AI Artifacts:**
* [ ] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
* [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
* [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
* [ ] Copilot agent (`.github/agents/*.agent.md`)
* [x] Copilot skill (`.github/skills/*/SKILL.md`)
> Note for AI Artifact Contributors:
>
> * Agents: Research, indexing/referencing other project (using standard
VS Code GitHub Copilot/MCP tools), planning, and general implementation
agents likely already exist. Review `.github/agents/` before creating
new ones.
> * Skills: Must include both bash and PowerShell scripts. See
[Skills](../docs/contributing/skills.md).
> * Model Versions: Only contributions targeting the **latest Anthropic
and OpenAI models** will be accepted. Older model versions (e.g.,
GPT-3.5, Claude 3) will be rejected.
> * See [Agents Not
Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).
**Other:**
* [x] Script/automation (`.ps1`, `.sh`, `.py`)
* [ ] Other (please describe):
## Sample Prompts (for AI Artifact Contributions)
**User Request:**
> Generate a PR reference excluding YAML files and using merge-base
comparison
**Execution Flow:**
1. Agent reads SKILL.md and identifies `generate.ps1` as the appropriate
script
2. Calls `scripts/generate.ps1 -BaseBranch auto -MergeBase -ExcludeExt
yml,yaml`
3. Script resolves the remote default branch via `git symbolic-ref
refs/remotes/origin/HEAD`
4. Resolves merge-base between HEAD and the detected branch
5. Generates diff excluding `*.yml` and `*.yaml` files via pathspec
negation
6. Writes XML output to `.copilot-tracking/pr/pr-reference.xml`
**Output Artifacts:**
- `.copilot-tracking/pr/pr-reference.xml` — structured XML with commit
history and filtered diff
**Success Indicators:**
- Console output shows "Comparison mode: merge-base" and "Note:
Extensions excluded from diff: yml, yaml"
- XML output contains only non-YAML file diffs
- Commit range uses merge-base commit SHA instead of direct branch ref
## Testing
### Pester Tests
All 155 non-integration tests passed with 0 failures:
```json
{
"Timestamp": "2026-03-16T13:12:12.4376485+00:00",
"Result": "Passed",
"TotalCount": 180,
"PassedCount": 155,
"FailedCount": 0,
"SkippedCount": 0,
"Duration": "00:02:57.4373385",
"CoveragePercent": 4.71
}
```
(25 integration-tagged tests excluded per default Pester filter
configuration.)
### Code Coverage (pr-reference package)
Coverage computed from JaCoCo report for the pr-reference scripts
package:
| Script | Line Coverage |
|--------------------|---------------|
| generate.ps1 | 136/142 = 95.8% |
| list-changed-files.ps1 | 63/67 = 94.0% |
| read-diff.ps1 | 101/105 = 96.2% |
| shared.psm1 | 24/24 = 100.0% |
| **Package total** | **324/338 = 95.9%** |
### shellcheck
Both bash scripts pass with zero warnings:
```
shellcheck .github/skills/shared/pr-reference/scripts/generate.sh .github/skills/shared/pr-reference/scripts/list-changed-files.sh
# Exit code: 0, no output
```
### PSScriptAnalyzer
All PowerShell scripts pass with zero violations:
```
Invoke-ScriptAnalyzer -Path '.github/skills/shared/pr-reference/scripts/' -Recurse
# 0 violations
```
### Skill Structure Validation
```
npm run validate:skills
# ✅ pr-reference — passed
```
### Plugin Generation & Validation
```
npm run plugin:generate
# 11 plugin(s) generated, 0 errors
npm run plugin:validate
# 11 collections validated, 0 errors
```
### Manual Testing
- [ ] Manually test calling the skill with the newer parameters and
validate the correct scripts execute the required git commands
## Checklist
### Required Checks
* [x] Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [x] Changes are backwards compatible (if applicable)
* [x] Tests added for new functionality (if applicable)
### AI Artifact Contributions
<!-- If contributing an agent, prompt, instruction, or skill, complete
these checks -->
* [ ] Used `/prompt-analyze` to review contribution
* [ ] Addressed all feedback from `prompt-builder` review
* [ ] Verified contribution follows common standards and type-specific
requirements
### Required Automated Checks
The following validation commands must pass before merging:
* [x] Markdown linting: `npm run lint:md`
* [x] Spell checking: `npm run spell-check`
* [x] Frontmatter validation: `npm run lint:frontmatter`
* [x] Skill structure validation: `npm run validate:skills`
* [x] Link validation: `npm run lint:md-links`
* [x] PowerShell analysis: `npm run lint:ps`
* [x] Plugin freshness: `npm run plugin:generate`
## Security Considerations
<!-- 1 parent e49a1b5 commit 26a32ea
12 files changed
+845
-82
lines changed| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| |||
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
28 | | - | |
| 28 | + | |
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
| |||
36 | 36 | | |
37 | 37 | | |
38 | 38 | | |
| 39 | + | |
39 | 40 | | |
40 | 41 | | |
41 | 42 | | |
42 | 43 | | |
| 44 | + | |
43 | 45 | | |
44 | 46 | | |
45 | 47 | | |
46 | 48 | | |
47 | 49 | | |
48 | 50 | | |
49 | | - | |
50 | | - | |
51 | | - | |
52 | | - | |
53 | | - | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
54 | 59 | | |
55 | 60 | | |
56 | 61 | | |
| |||
63 | 68 | | |
64 | 69 | | |
65 | 70 | | |
66 | | - | |
67 | | - | |
68 | | - | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
69 | 76 | | |
70 | 77 | | |
71 | 78 | | |
72 | | - | |
73 | | - | |
74 | | - | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
75 | 84 | | |
76 | 85 | | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
77 | 93 | | |
78 | 94 | | |
79 | 95 | | |
| |||
97 | 113 | | |
98 | 114 | | |
99 | 115 | | |
100 | | - | |
101 | | - | |
102 | | - | |
103 | | - | |
104 | | - | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
105 | 121 | | |
106 | 122 | | |
Lines changed: 130 additions & 22 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
14 | 14 | | |
15 | 15 | | |
16 | 16 | | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
17 | 22 | | |
18 | 23 | | |
19 | 24 | | |
20 | 25 | | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
21 | 34 | | |
22 | 35 | | |
23 | 36 | | |
| |||
28 | 41 | | |
29 | 42 | | |
30 | 43 | | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
31 | 47 | | |
32 | 48 | | |
33 | 49 | | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
34 | 56 | | |
35 | 57 | | |
36 | 58 | | |
| |||
88 | 110 | | |
89 | 111 | | |
90 | 112 | | |
| 113 | + | |
91 | 114 | | |
92 | 115 | | |
| 116 | + | |
| 117 | + | |
93 | 118 | | |
94 | 119 | | |
95 | 120 | | |
96 | 121 | | |
97 | 122 | | |
98 | 123 | | |
99 | | - | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
100 | 128 | | |
101 | 129 | | |
102 | 130 | | |
| |||
105 | 133 | | |
106 | 134 | | |
107 | 135 | | |
| 136 | + | |
| 137 | + | |
108 | 138 | | |
109 | 139 | | |
110 | 140 | | |
111 | | - | |
112 | | - | |
113 | | - | |
114 | | - | |
115 | | - | |
116 | | - | |
117 | | - | |
118 | | - | |
119 | | - | |
120 | | - | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
121 | 144 | | |
122 | 145 | | |
123 | 146 | | |
124 | | - | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
125 | 170 | | |
126 | 171 | | |
127 | 172 | | |
| |||
244 | 289 | | |
245 | 290 | | |
246 | 291 | | |
247 | | - | |
| 292 | + | |
248 | 293 | | |
249 | 294 | | |
250 | 295 | | |
251 | 296 | | |
| 297 | + | |
| 298 | + | |
| 299 | + | |
| 300 | + | |
252 | 301 | | |
253 | 302 | | |
254 | 303 | | |
| |||
258 | 307 | | |
259 | 308 | | |
260 | 309 | | |
261 | | - | |
| 310 | + | |
| 311 | + | |
| 312 | + | |
| 313 | + | |
| 314 | + | |
| 315 | + | |
| 316 | + | |
262 | 317 | | |
263 | 318 | | |
264 | 319 | | |
| 320 | + | |
| 321 | + | |
265 | 322 | | |
266 | | - | |
| 323 | + | |
| 324 | + | |
| 325 | + | |
| 326 | + | |
| 327 | + | |
| 328 | + | |
267 | 329 | | |
268 | 330 | | |
269 | 331 | | |
| |||
284 | 346 | | |
285 | 347 | | |
286 | 348 | | |
| 349 | + | |
| 350 | + | |
| 351 | + | |
| 352 | + | |
287 | 353 | | |
288 | 354 | | |
289 | 355 | | |
| |||
293 | 359 | | |
294 | 360 | | |
295 | 361 | | |
296 | | - | |
| 362 | + | |
| 363 | + | |
| 364 | + | |
| 365 | + | |
| 366 | + | |
| 367 | + | |
| 368 | + | |
297 | 369 | | |
298 | 370 | | |
299 | 371 | | |
| 372 | + | |
| 373 | + | |
300 | 374 | | |
301 | | - | |
| 375 | + | |
| 376 | + | |
| 377 | + | |
| 378 | + | |
| 379 | + | |
| 380 | + | |
302 | 381 | | |
303 | 382 | | |
304 | 383 | | |
| |||
413 | 492 | | |
414 | 493 | | |
415 | 494 | | |
416 | | - | |
| 495 | + | |
| 496 | + | |
| 497 | + | |
417 | 498 | | |
418 | 499 | | |
| 500 | + | |
| 501 | + | |
| 502 | + | |
| 503 | + | |
419 | 504 | | |
420 | 505 | | |
421 | 506 | | |
| |||
427 | 512 | | |
428 | 513 | | |
429 | 514 | | |
| 515 | + | |
| 516 | + | |
| 517 | + | |
430 | 518 | | |
431 | 519 | | |
432 | 520 | | |
| 521 | + | |
| 522 | + | |
| 523 | + | |
| 524 | + | |
| 525 | + | |
| 526 | + | |
433 | 527 | | |
434 | 528 | | |
435 | 529 | | |
| |||
438 | 532 | | |
439 | 533 | | |
440 | 534 | | |
| 535 | + | |
| 536 | + | |
| 537 | + | |
| 538 | + | |
| 539 | + | |
441 | 540 | | |
442 | 541 | | |
443 | 542 | | |
| |||
454 | 553 | | |
455 | 554 | | |
456 | 555 | | |
457 | | - | |
| 556 | + | |
458 | 557 | | |
459 | 558 | | |
460 | 559 | | |
461 | | - | |
462 | | - | |
| 560 | + | |
| 561 | + | |
463 | 562 | | |
464 | 563 | | |
465 | 564 | | |
| |||
475 | 574 | | |
476 | 575 | | |
477 | 576 | | |
| 577 | + | |
| 578 | + | |
| 579 | + | |
| 580 | + | |
| 581 | + | |
| 582 | + | |
| 583 | + | |
| 584 | + | |
| 585 | + | |
478 | 586 | | |
479 | 587 | | |
480 | 588 | | |
| |||
490 | 598 | | |
491 | 599 | | |
492 | 600 | | |
493 | | - | |
| 601 | + | |
494 | 602 | | |
495 | 603 | | |
496 | 604 | | |
| |||
0 commit comments