document PowerShell requirements for build analysis script

Add PowerShell installation instructions and version requirements:
- Minimum: PowerShell 5.1 (Windows built-in)
- Recommended: PowerShell 7+ (cross-platform)
- Always prefer pwsh over powershell.exe when available

Add runtime version check to script with helpful error messages.

🤖 Co-Authored-By: Claude Code <noreply@anthropic.com>

Author: lucaspimentel

.claude/skills/troubleshoot-ci-build/README.md

@@ -115,10 +115,48 @@ Ask for details on a specific failure to get:
 
 ## Requirements
 
+- **PowerShell** - [Installation instructions](#installing-powershell)
+  - **Recommended**: PowerShell 7+ (`pwsh`) - cross-platform, modern features
+  - **Minimum**: PowerShell 5.1 (`powershell.exe` on Windows only)
 - **GitHub CLI** (`gh`) authenticated (for PR analysis)
 - **Azure CLI** (`az`) authenticated to DataDog organization
 - **Internet connection** to fetch build data
 
+### Installing PowerShell
+
+**Recommended**: Install PowerShell 7+ for the best experience and cross-platform support.
+
+**Windows**:
+```powershell
+winget install Microsoft.PowerShell
+```
+
+**macOS**:
+```bash
+brew install powershell/tap/powershell
+```
+
+**Linux (Ubuntu/Debian)**:
+```bash
+# Download the Microsoft repository GPG keys
+wget -q https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb
+
+# Register the Microsoft repository GPG keys
+sudo dpkg -i packages-microsoft-prod.deb
+
+# Update apt and install PowerShell
+sudo apt-get update
+sudo apt-get install -y powershell
+```
+
+**Linux (Other distributions)** and more details: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell
+
+**Verify installation**:
+```bash
+pwsh -Version
+# Should output: PowerShell 7.x.x or higher
+```
+
 ## Related Scripts (tracer/tools/)
 
 This skill uses the following standalone scripts that can also be run manually:

.claude/skills/troubleshoot-ci-build/SKILL.md

@@ -11,10 +11,35 @@ allowed-tools: WebFetch, Bash(gh pr checks:*), Bash(az devops invoke:*), Bash(az
 
 Troubleshoot Azure DevOps pipeline failures with automated analysis and comparison against master builds.
 
+## Prerequisites
+
+**CRITICAL**: This skill requires PowerShell to run the build analysis script.
+
+**PowerShell version requirements**:
+- **Recommended**: PowerShell 7+ (`pwsh`) - cross-platform, modern features
+- **Minimum**: PowerShell 5.1 (`powershell.exe` on Windows only)
+
+**Installation**:
+- Windows: `winget install Microsoft.PowerShell` (or use built-in PowerShell 5.1)
+- macOS: `brew install powershell/tap/powershell`
+- Linux: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux
+
+**If the user does not have PowerShell installed**:
+1. Check for `pwsh` first: `pwsh -Version`
+2. If not found and on Windows, check for PowerShell 5.1: `powershell -NoProfile -Command '$PSVersionTable.PSVersion'`
+3. If neither found or version is too old, provide installation instructions from [README.md](README.md#installing-powershell)
+4. Do NOT attempt to replicate the script functionality using bash/jq - the logic is too complex
+
+**Always prefer `pwsh` over `powershell.exe`** when both are available (better cross-platform compatibility and modern features).
+
+**Other requirements**:
+- GitHub CLI (`gh`) authenticated (for PR analysis)
+- Azure CLI (`az`) configured
+
 ## Additional Resources
 
 - **[failure-patterns.md](failure-patterns.md)** - Reference guide with known CI failure patterns, categorization rules, and decision trees. Load when you need to categorize a failure type or compare against historical patterns.
-- **[README.md](README.md)** - User-facing documentation with usage examples. Reference when explaining skill capabilities to users.
+- **[README.md](README.md)** - User-facing documentation with usage examples and installation instructions. Reference when explaining skill capabilities to users.
 - **[scripts-reference.md](scripts-reference.md)** - Documentation for `Get-AzureDevOpsBuildAnalysis.ps1` script (parameters, usage, output structure).
 
 ## Task

.claude/skills/troubleshoot-ci-build/scripts-reference.md

@@ -12,8 +12,15 @@ This document describes reusable PowerShell scripts for Azure DevOps CI troubles
 
 ### Prerequisites
 
-- Azure CLI (`az`) authenticated to DataDog organization
-- GitHub CLI (`gh`) authenticated (only if using `-PullRequest` parameter)
+- **PowerShell 5.1+** - Required to run this script
+  - **Recommended**: PowerShell 7+ (`pwsh`) for cross-platform support
+  - **Minimum**: PowerShell 5.1 (`powershell.exe` on Windows)
+  - Installation: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell
+  - Verify: `pwsh -Version` or `powershell -NoProfile -Command '$PSVersionTable.PSVersion'`
+- **Azure CLI** (`az`) authenticated to DataDog organization
+- **GitHub CLI** (`gh`) authenticated (only if using `-PullRequest` parameter)
+
+**Note**: This script uses PowerShell-specific features (e.g., `-notin` operator, `HashSet<T>`, `Invoke-RestMethod`) that cannot be easily replicated in bash. Always prefer `pwsh` over `powershell.exe` when both are available.
 
 ### Parameters
 

tracer/tools/Get-AzureDevOpsBuildAnalysis.ps1

@@ -86,6 +86,24 @@ param(
 
 $ErrorActionPreference = 'Stop'
 
+# Verify PowerShell version (requires 5.1+ for ConvertTo-Json -Depth and -notin operator)
+if ($PSVersionTable.PSVersion.Major -lt 5 -or
+    ($PSVersionTable.PSVersion.Major -eq 5 -and $PSVersionTable.PSVersion.Minor -lt 1)) {
+    Write-Error @"
+This script requires PowerShell 5.1 or higher.
+Current version: $($PSVersionTable.PSVersion)
+
+Install PowerShell 7+ (recommended for cross-platform support):
+- Windows: winget install Microsoft.PowerShell
+- macOS: brew install powershell/tap/powershell
+- Linux: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux
+
+Or use PowerShell 5.1 (Windows only):
+- Included with Windows 10/11 - run with: powershell.exe (not powershell.exe -Version 2)
+"@
+    exit 1
+}
+
 #region Helper Functions
 
 function Invoke-AzDevOpsApi {