---
name: powershell-code-review
description: "Use when: reviewing or repairing PowerShell 7 scripts and modules with parser diagnostics, PSScriptAnalyzer findings, approved verbs, command metadata, pipeline behavior, error handling, test gaps, and security risks."
argument-hint: "PowerShell files or change to review"
---

# PowerShell Code Review

Review for behavioral defects first, then compatibility, safety, maintainability, and style.

## Workflow

1. Identify changed PowerShell files and the public behavior they affect. Read nearby tests and call sites before proposing changes.
2. When `psmcp-builtin` is available, read every changed `.ps1`, `.psm1`, and `.psd1` file and call `parse_script` with its text. If it is unavailable, identify parsing as unverified rather than claiming validation.
3. Stop and fix parse errors before deeper review. Do not infer runtime behavior from an invalid AST.
4. Recommend PSScriptAnalyzer as an optional local or CI check when the repository uses it; do not claim an analyzer MCP tool exists or that analysis ran unless its result was observed.
5. Review behavior not fully covered by static analysis:
   - parameter-set ambiguity and accidental positional binding
   - pipeline handling across `begin`, `process`, and `end`
   - output-stream pollution
   - mutation without `ShouldProcess`
   - broad catches, swallowed errors, and unsafe retries
   - wildcard exports and import-time side effects
   - secrets in source, logs, errors, or defaults
   - platform-specific paths or commands despite a cross-platform claim
6. Use `get_command_metadata` before asserting command parameters when `psmcp-builtin` is available. Otherwise use authoritative documentation and mark unresolved uncertainty.
7. Review Pester coverage using the `powershell-pester-testing` skill. If the `powershell-pester-testing` skill is unavailable, review test coverage directly by checking that each public function has `Describe`/`It` blocks covering success, error, and parameter-set paths, and state that the dedicated skill was not applied. Do not execute tests through this MCP server.
8. Present findings ordered by severity with file and line references, impact, and the smallest defensible fix.
9. When asked to repair, fix root causes in focused edits, then rerun available parser checks and, only if the user has explicitly asked in this conversation to run PSScriptAnalyzer or Pester, run those commands in the terminal for touched files; otherwise recommend the exact command and mark results as not observed.

## Severity

- **Critical**: credential exposure, destructive behavior without a meaningful guard, or arbitrary code execution introduced by the change
- **High**: incorrect results, uncaught terminating failure, data loss, or broken public contract
- **Medium**: unreliable pipeline behavior, compatibility regression, weak validation, or important missing test
- **Low**: maintainability or convention issue with limited behavioral risk

## Analyzer Interpretation

- Treat diagnostics as evidence, not final judgment.
- Never suppress a rule merely to make the report empty.
- Prefer a code correction; when suppression is justified, keep it narrow and document the invariant.
- State clearly that static analysis does not prove runtime correctness.

## Boundaries

- `psmcp-builtin` parses supplied script text and returns read-only command discovery, metadata, and help. It does not execute the parsed script.
- Do not claim PSScriptAnalyzer or Pester ran unless the user explicitly asked in this conversation to run it and its local or CI command was executed and observed.

## Source

- [PSScriptAnalyzer overview](https://learn.microsoft.com/powershell/utility-modules/psscriptanalyzer/overview)