Summary

The pr-reference skill at .github/skills/shared/pr-reference/ provides diff generation, changed-file listing, and chunk reading for PR workflows. Several agents need diff-mode analysis capabilities that go beyond what the skill currently supports, requiring workarounds with raw git commands. Enhancing the skill directly benefits any agent or workflow that consumes branch diffs, including PR description generation, code review, and security analysis.

Current Behavior

The skill's generate.sh/ps1 and list-changed-files.sh/ps1 scripts support:

• --base-branch with a hardcoded default of origin/main
• --type filtering for a single change type (added, deleted, modified, renamed, or all)
• --no-md-diff to exclude markdown files from the diff
• --format for output as plain text, JSON, or markdown

Expected Behavior

The skill supports flexible base branch detection, merge-base comparison, multi-type file filtering, and extension/path exclusion across both bash and PowerShell implementations.

Root Cause

The skill was built for PR description generation against origin/main with minimal filtering. Broader usage scenarios (security analysis, implementation validation, RPI validation) require more flexible diff scoping.

Files Requiring Changes

Acceptance Criteria

• generate.sh and generate.ps1 support --merge-base to compare using git merge-base instead of direct diff
• generate.sh and generate.ps1 support automatic default branch detection via --base-branch auto (resolves origin/HEAD and falls back gracefully)
• generate.sh and generate.ps1 support --exclude-ext to exclude files by extension from the diff output
• generate.sh and generate.ps1 support --exclude-path to exclude files by path prefix from the diff output
• list-changed-files.sh and list-changed-files.ps1 support comma-separated --type values (e.g., --type added,modified,renamed)
• list-changed-files.sh and list-changed-files.ps1 support --exclude-type as an alternative to --type for exclusion-based filtering
• SKILL.md Parameters Reference table is updated to document all new flags
• Pester tests cover all new parameters and edge cases (empty results, invalid inputs, combined flags)
• Pester test code coverage for pr-reference scripts is above 80%
• Bash scripts pass shellcheck validation
• PowerShell scripts pass PSScriptAnalyzer validation (npm run lint:ps)
• All existing tests continue to pass (npm run test:ps)
• Collection manifests are updated if any paths change (collections/hve-core.collection.yml, collections/hve-core-all.collection.yml, collections/ado.collection.yml)
• Plugin outputs are regenerated (npm run plugin:generate) and pass validation (npm run plugin:validate)
• All CI checks pass (npm run lint:all, npm run validate:skills)
• Manually test calling the skill with the requirement to call the right script with the newer parameters, and validate the correct scripts execute the required git commands.

Unit Testing and Code Coverage Requirements

Pester tests are required for all new parameters across the PowerShell scripts. Test code coverage for pr-reference scripts must exceed 80%. The --no-md-diff flag in generate.sh/generate.ps1 serves as the closest existing pattern for the new exclusion flags.

RPI Framework Starter Prompts

Phase 1: Research

Select Task Researcher from the agent picker at the bottom of the GitHub Copilot Chat prompt pane, then send the following prompt:

Research enhancing the pr-reference skill with flexible filtering and base branch detection. Review the details from issue #1011. Investigate: (1) Read generate.sh and generate.ps1 fully to understand how --no-md-diff and --base-branch are implemented. (2) Read list-changed-files.sh and list-changed-files.ps1 to understand the --type filtering logic. (3) Read shared.psm1 for shared helper functions. (4) Review git documentation for git merge-base and git symbolic-ref refs/remotes/origin/HEAD behavior. (5) Check existing Pester test coverage in scripts/tests/. (6) Check codecov.yml and scripts/tests/pester.config.ps1 for coverage requirements. (7) Verify how --exclude-ext and --exclude-path map to git pathspec patterns.

Phase 2: Plan

Select Task Planner from the agent picker at the bottom of the GitHub Copilot Chat prompt pane, then send the following prompt:

Plan enhancing the pr-reference skill using the research document (attach it from above result).

Phase 3: Implement

Select Task Implementor from the agent picker at the bottom of the GitHub Copilot Chat prompt pane. Attach the ....instructions.md generated by the Planner, then send the following prompt:

Implement the pr-reference skill enhancements following the plan attached.

Phase 4: Review

Select Task Reviewer from the agent picker at the bottom of the GitHub Copilot Chat prompt pane, then send the following prompt:

Review pr-reference skill enhancements. Verify the initial research and plan (attach the files), and cross check with the issue content.

References

• .github/skills/shared/pr-reference/scripts/generate.sh — bash diff generation
• .github/skills/shared/pr-reference/scripts/generate.ps1 — PowerShell diff generation
• .github/skills/shared/pr-reference/scripts/list-changed-files.sh — bash file listing
• .github/skills/shared/pr-reference/scripts/list-changed-files.ps1 — PowerShell file listing
• .github/skills/shared/pr-reference/scripts/shared.psm1 — shared PowerShell helpers
• .github/skills/shared/pr-reference/SKILL.md — skill documentation