powershell-windows

PowerShell — Windows Automation Mastery

Mandatory Pre-Flight Context Inspection

Before writing PowerShell .ps1 scripts or Windows automation commands, you MUST inspect:

1. Object Pipeline vs String Parsing Rule (Section 23) → Operate directly on .NET object properties (Get-Process | Stop-Process); ban string splitting/parsing
2. Mandatory Script Strict Mode Header (Section 43) → Always declare $ErrorActionPreference = "Stop" and Set-StrictMode -Version Latest at top of automation scripts
3. Process-Scoped Execution Policy Bypass (Section 68) → Use process-level policy override (powershell.exe -ExecutionPolicy Bypass -File ...); ban system-wide Set-ExecutionPolicy Unrestricted

PowerShell — Windows Automation Mastery

1. The Object Pipeline

Unlike Bash where everything is strings (requiring awk/grep), PowerShell passes structured .NET class instances between commands.

# ❌ BAD: Attempting to treat PowerShell like Bash (String Parsing)
Get-Process | Out-String -Stream | Select-String "node" | ForEach-Object { $id = ($_ -split '\s+')[8]; Stop-Process -Id $id }

# ✅ GOOD: Accessing Object Properties Directly
Get-Process -Name "node" | Stop-Process -Force

# Filtering objects (Where-Object)
Get-Service | Where-Object Status -eq 'Running' | Select-Object Name, DisplayName

# Accessing methods natively on the object
$files = Get-ChildItem -Path "C:\logs" -Filter "*.log"
$files | ForEach-Object { $_.Delete() }

2. Strict Error Handling (The Windows equivalent of set -e)

By default, PowerShell prints an error but keeps running. You MUST enforce strict halting for automation scripts.

# Mandatory header for reliable automation scripts
$ErrorActionPreference = "Stop"
Set-StrictMode -Version Latest

try {
    # If this fails, it jumps straight to catch block instead of continuing
    Copy-Item "C:\Source\configs.json" -Destination "C:\Dest\"

    $config = Get-Content "C:\Dest\configs.json" | ConvertFrom-Json
} catch {
    Write-Error "Deployment failed during config copy: $_"
    exit 1
} finally {
    # Cleanup block executes regardless of success or failure
    Remove-Item "C:\Dest\temp" -Recurse -ErrorAction Ignore
}

3. Execution Policies & Execution

Windows restricts running .ps1 files by default for security.

# Temporarily bypass the policy for a single script execution (CI/CD pattern)
powershell.exe -ExecutionPolicy Bypass -File .\Deploy-App.ps1

# ❌ HALLUCINATION TRAP: Do NOT instruct users to run `Set-ExecutionPolicy Unrestricted`
# This lowers the permanent security posture of the entire operating system.
# Use Bypass only at the process level.

4. Manipulating Structured Formats Natively

Because PowerShell is built on .NET, parsing JSON, XML, and CSV is native.

# JSON
$config = Get-Content .\appsettings.json | ConvertFrom-Json
$config.Database.ConnectionString = "Server=Prod;"
$config | ConvertTo-Json -Depth 10 | Set-Content .\appsettings.json

# CSV (No AWK needed)
$users = Import-Csv .\users.csv
$users | Where-Object Role -eq "Admin" | Export-Csv .\admins.csv -NoTypeInformation

# API Requests (Invoke-RestMethod automatically parses JSON into PowerShell objects)
$response = Invoke-RestMethod -Uri "https://api.github.com/users/github"
Write-Host "GitHub has $($response.public_repos) public repositories."

5. Providers and Drives

PowerShell extends the "file system" concept to the Registry, Environment Variables, and Certificates.

# Environment variables (Env: drive)
$env:PATH += ";C:\Custom\Bin"
Write-Host $env:COMPUTERNAME

# Registry (HKCU: and HKLM: drives)
Get-ChildItem -Path "HKLM:\Software\Microsoft\Windows\CurrentVersion\Run"

# Certificates (Cert: drive)
Get-ChildItem -Path "Cert:\LocalMachine\My" | Where-Object Subject -match "example.com"

AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:

1. Over-engineering: Proposing complex abstractions or distributed systems when a simpler approach suffices.
2. Hallucinated Libraries/Methods: Using non-existent methods or packages. Always // VERIFY or check package.json / requirements.txt.
3. Skipping Edge Cases: Writing the "happy path" and ignoring error handling, timeouts, or data validation.
4. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
5. Silent Degradation: Catching and suppressing errors without logging or re-raising.

Slash command: /review or /tribunal-full Active reviewers: logic-reviewer · security-auditor

❌ Forbidden AI Tropes

1. Blind Assumptions: Never make an assumption without documenting it clearly with // VERIFY: [reason].
2. Silent Degradation: Catching and suppressing errors without logging or handling.
3. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.

Review these questions before confirming output:

✅ Did I rely ONLY on real, verified tools and methods?
✅ Is this solution appropriately scoped to the user's constraints?
✅ Did I handle potential failure modes and edge cases?
✅ Have I avoided generic boilerplate that doesn't add value?

🛑 Verification-Before-Completion (VBC) Protocol

CRITICAL: You must follow a strict "evidence-based closeout" state machine.

• ❌ Forbidden: Declaring a task complete because the output "looks correct."
• ✅ Required: You are explicitly forbidden from finalizing any task without providing concrete evidence (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

Pre-Flight Checklist

• Have I reviewed the user's specific constraints and requests?
• Have I checked the environment for relevant existing implementations?

VBC Protocol (Verification-Before-Completion)

You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.

🤖 LLM-Specific Traps

AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:

1. Over-engineering: Proposing complex abstractions or distributed systems when a simpler approach suffices.
2. Hallucinated Libraries/Methods: Using non-existent methods or packages. Always // VERIFY or check package.json / requirements.txt.
3. Skipping Edge Cases: Writing the "happy path" and ignoring error handling, timeouts, or data validation.
4. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
5. Silent Degradation: Catching and suppressing errors without logging or re-raising.

🏛️ Tribunal Integration (Anti-Hallucination)

Slash command: /review or /tribunal-full Active reviewers: logic-reviewer · security-auditor

❌ Forbidden AI Tropes

1. Blind Assumptions: Never make an assumption without documenting it clearly with // VERIFY: [reason].
2. Silent Degradation: Catching and suppressing errors without logging or handling.
3. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.

✅ Pre-Flight Self-Audit

Review these questions before confirming output:

✅ Did I rely ONLY on real, verified tools and methods?
✅ Is this solution appropriately scoped to the user's constraints?
✅ Did I handle potential failure modes and edge cases?
✅ Have I avoided generic boilerplate that doesn't add value?

🛑 Verification-Before-Completion (VBC) Protocol

CRITICAL: You must follow a strict "evidence-based closeout" state machine.

• ❌ Forbidden: Declaring a task complete because the output "looks correct."
• ✅ Required: You are explicitly forbidden from finalizing any task without providing concrete evidence (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.