Add AI skills: analyze-debug-files, find-related-github-issues, trace-code-introduction

[David Paulson (dpaulson45)]

Summary

Adds three new Copilot AI skills for CSS-Exchange debug-log triage, plus a supporting extension to the existing find-release-tag-for-script-version skill.

New skills

• analyze-debug-files — end-to-end pipeline that ingests a CSS-Exchange debug log, identifies the source script + release-tag baseline, walks the dependency graph via .build/Build.ps1 output, and writes a root-cause report (DebugAnalysis-<timestamp>.md) into the caller-supplied directory.
• find-related-github-issues — searches microsoft/CSS-Exchange issues for prior reports of a given exception. Invocable directly during triage or as a Step 7 sub-invocation of analyze-debug-files.
• trace-code-introduction — resolves a specific source line + range at a pinned SHA to the commit that introduced it (via git log -L and git blame). Used by analyze-debug-files to attribute unhandled exceptions to their originating change.

Extension

• find-release-tag-for-script-version now emits a ConfirmedCommitSha field alongside ConfirmedTag. analyze-debug-files needs the 40-character SHA to build a scratch worktree deterministically and to key its per-SHA dependency cache; a tag alone is ambiguous once tags are re-pointed.

Notable design decisions

• Per-SHA dependency cache at %LOCALAPPDATA%\CSS-Exchange\dependency-cache\<sha>\. On cache hit, analyze-debug-files skips the ~107 s .build/Build.ps1 invocation (measured ~74× speedup). The cache is worktree-independent — XML keys are normalized from absolute worktree paths to repo-relative paths so Steps 6-8 can read source with git show <sha>:<path> regardless of which run produced the cache.
• Report fidelity guardrails — Step 8's template enforces strict source-slice rules (# L<n> trailing annotations, no ellipses, consecutive-line check) with a post-render regex assertion so cited source cannot be silently truncated or paraphrased.
• Trust model — personal-machine, no ownership preflight; the caller's supplied output directory is trusted, and the report is written directly there.
• Input validation — all three new skills validate gh CLI arguments, git pathspecs, and shell-metacharacter surfaces before invoking subprocesses (see Get-SafeQueryPhrase, allow-list regexes in Trace-CodeIntroduction.ps1).

Testing

• Pre-commit hooks (PSScriptAnalyzer + formatter) pass on all 4 commits.
• .build\SpellCheck.ps1 — clean (0 issues, 810 files).
• Manual end-to-end validated against a real HealthChecker debug log (PS 4.0 / Server 2012 R2 / -ForceLegacy scenario). Cache miss + cache hit both verified; normalized XML keys resolve via git show <sha>:<path>.

Commits

1. Extend find-release-tag-for-script-version with ConfirmedCommitSha + cspell dictionary additions.
2. Add find-related-github-issues skill.
3. Add trace-code-introduction skill.
4. Add analyze-debug-files skill.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[David Paulson (dpaulson45)]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).

[Copilot]

🟡 Changes recommended

Unresolved critical and moderate findings remain.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds three Copilot skills for CSS-Exchange debug-log triage, GitHub issue correlation, and code-introduction tracing, plus confirmed commit-SHA support for release lookup.

Changes:

• Adds debug-log metadata parsing, dependency caching, and report generation.
• Adds related GitHub issue search and source-history tracing.
• Extends release resolution with ConfirmedCommitSha and updates spelling data.

File summaries

File	Description
.github/skills/trace-code-introduction/Trace-CodeIntroduction.ps1	Traces source ranges to introducing commits.
.github/skills/trace-code-introduction/SKILL.md	Documents code-introduction tracing.
.github/skills/find-release-tag-for-script-version/SKILL.md	Documents confirmed commit-SHA output.
.github/skills/find-release-tag-for-script-version/Find-ReleaseTagForScriptVersion.ps1	Resolves release tags and commit SHAs.
.github/skills/find-related-github-issues/SKILL.md	Documents related-issue lookup.
.github/skills/find-related-github-issues/Find-RelatedGitHubIssues.ps1	Searches and classifies related issues.
.github/skills/analyze-debug-files/SKILL.md	Defines the end-to-end analysis workflow.
.github/skills/analyze-debug-files/Get-DebugFileMetadata.ps1	Parses and sanitizes debug logs.
.build/cspell-words.txt	Adds skill-specific dictionary terms.

Review details

Suppressed comments (12)

.github/skills/analyze-debug-files/Get-DebugFileMetadata.ps1:555

• The sanitizer removes C0 controls and DEL, but it leaves the C1 range U+0080–U+009F. Those characters can be returned in snippets and violate the report's explicit no-stray-C0/C1 assertion. Extend the character class to cover \x7F-\x9F.

    '[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]',

.github/skills/analyze-debug-files/Get-DebugFileMetadata.ps1:672

• The regex-timeout fallback uses code -ge 0x20 as its printable test, which also accepts C1 controls U+0080–U+009F. A timeout therefore bypasses the normal sanitizer's intended output guarantee and can still place those controls in the report. Use the same printable range as the normal path here.

            if (($code -ge 0x20 -and $code -ne 0x7F) -or $code -eq 0x09) {

.github/skills/analyze-debug-files/Get-DebugFileMetadata.ps1:992

• HealthChecker's Get-ErrorsThatOccurred also emits ----Errors that occurred that was not handled remotely---- after the normal unhandled footer (see Diagnostics/HealthChecker/Helpers/Get-ErrorsThatOccurred.ps1:37-40). This state machine only recognizes the handled/unhandled headers, so a run with hidden remote errors is still marked SummaryComplete with UnhandledCount=0, causing the analyzer to report a clean run while silently dropping those errors. Add a remote-section signal/count or downgrade completion when that header is present.

                } elseif ($Script:UnhandledSummaryHeaderRegex.IsMatch($line)) {
                    $summaryState = 'unhandled'
                    $summaryUnhandledCount = 0
                    $unhandledHeaderLine = $lineNumber
                    $unhandledHeaderCount++

.github/skills/analyze-debug-files/Get-DebugFileMetadata.ps1:417

• The logger formats [System.DateTime]::Now with the machine's culture (Shared/LoggerFunctions.ps1:60-63), so the common en-US output includes an AM/PM suffix. This regex and the AcceptedTimestampFormats below reject that form, leaving $ts null on every timestamped line; version candidates, completion signals, summary events, and body-evidence correlation then become unavailable for ordinary HealthChecker logs. Parse the logger's culture-dependent format (or add the 12-hour forms) consistently to the framing regex and accepted formats.

    '\A\s*\[(?<ts>[0-9]{1,2}/[0-9]{1,2}/[0-9]{4}\s+[0-9]{1,2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?)\]',

.github/skills/analyze-debug-files/Get-DebugFileMetadata.ps1:490

• This explanation cites Write-Host, but Get-ErrorsThatOccurred.ps1 emits both summary headers with Write-Verbose. The headers are untimestamped because the message starts with CRLF and the logger prefixes the timestamp before those newlines; documenting the actual mechanism is important because this comment justifies the anchored header regex.

# cannot forge an authoritative summary. HealthChecker emits these as
# untimestamped lines (the writers in Get-ErrorsThatOccurred.ps1 use
# `Write-Host`, not `Write-Verbose`), so anchor to line start/end.

.github/skills/analyze-debug-files/SKILL.md:576

• The suffix loop does not actually require a unique match: an absolute key can end with multiple repository paths, and the first hashtable key wins. For example, a key ending in .../Shared/OutputOverrides/Write-Error.ps1 can also match a shorter nested path if one exists, causing the dependency graph to resolve to the wrong source file. Collect suffix matches and accept only the unique/longest path (or reject ambiguity).

            if ($winKey.EndsWith($k, [System.StringComparison]::OrdinalIgnoreCase)) {
                return $Index[$k]

.github/skills/analyze-debug-files/SKILL.md:479

• A cache miss can be caused by an existing corrupt or incomplete $cacheDir (for example, invalid metadata). This branch deletes the newly built temp directory whenever the final directory exists, leaving the bad entry in place, so every subsequent run rebuilds and remains BuildOnly. Distinguish a valid concurrent winner from a stale invalid entry and replace or quarantine the latter.

                if (Test-Path -LiteralPath $cacheDir -PathType Container) {
                    Remove-Item -LiteralPath $tempDir -Recurse -Force -ErrorAction SilentlyContinue
                } else {
                    Move-Item -LiteralPath $tempDir -Destination $cacheDir
                    $materializationSource = 'BuildAndCached'

.github/skills/analyze-debug-files/SKILL.md:1041

• find-related-github-issues defines PartialLookup as usable retained results with incomplete coverage, not as an unavailable lookup. Treating every non-Ok status as unavailable would hide those matches from the report and contradict the sibling skill's contract; render retained results plus an incompleteness note for PartialLookup, reserving "unavailable" for the failure statuses.

**Failure modes.** Both skills return a `Status` field. When
`Status -ne 'Ok'`, render a single-line "lookup unavailable" note in
the corresponding subsection and continue with the report. A failing
provenance lookup MUST NOT abort the report.

.github/skills/analyze-debug-files/SKILL.md:437

• This invocation is still subject to the caller's $PSNativeCommandUseErrorActionPreference. When that preference is $true and Build.ps1 exits nonzero—the condition this step explicitly says may be cosmetic—PowerShell throws before the XML existence checks, so the documented BuildOnly/cache flow aborts instead of using the generated XML. Disable native-error promotion only around this invocation and restore the caller's value in finally, or invoke the process through an API that captures the exit code without throwing.

            & pwsh -NoProfile -File (Join-Path $worktreeRoot '.build\Build.ps1')

.github/skills/find-related-github-issues/Find-RelatedGitHubIssues.ps1:88

• Mandatory does not reject whitespace-only input. In that case normalization produces no query, the final status falls through to Ok with empty results, and callers can incorrectly report that no related issue exists instead of an invalid/failed lookup. Reject an empty or whitespace-only top-level exception before building the query list.

    [string]$TopLevelException,

.github/skills/find-related-github-issues/Find-RelatedGitHubIssues.ps1:128

• These replacements create literal placeholder tokens, but the subsequent exact GitHub query is built from the normalized phrase. For Failure at C:\a\b, the query becomes "Failure at path" after delimiter stripping; GitHub does not treat path as a wildcard, so an issue saying Failure at C:\other\d is never returned and normalization cannot provide the advertised stable matching. Build search phrases that omit volatile spans or use unquoted invariant terms, while keeping normalization for local classification.

    $s = [regex]::Replace($s, '[A-Za-z]:\\[^\s"'']+', '<path>')
    # Strip UNC paths.
    $s = [regex]::Replace($s, '\\\\[^\s"'']+', '<unc>')
    # Strip randomized temp module names like tmpEXO_3fzjpepe.o0p
    $s = [regex]::Replace($s, 'tmpEXO_[A-Za-z0-9]+(?:\.[A-Za-z0-9]+)?', 'tmpEXO_<random>')

.github/skills/find-release-tag-for-script-version/Find-ReleaseTagForScriptVersion.ps1:358

• For a valid empty gh release list response ([]), ConvertFrom-Json can produce $null (especially on Windows PowerShell 5.1). @($parsedReleases) then creates an array containing one null element, so the loop below throws Unexpected release entry shape from gh instead of reaching the not-found-no-candidates result. Preserve $null as an empty array before iterating.

    $releases = @($parsedReleases)

• Files reviewed: 9/9 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.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.