agentleFS
pnppnp/powershell/.agents/skills/whatif-audit/SKILL.md

whatif-audit

Skill915 starsChanged 5 days agoMITView on GitHub

Sweep PnP PowerShell cmdlets for -WhatIf, -Confirm and -Force that do not do what they promise - SupportsShouldProcess declared but never called, hand-declared WhatIf parameters, prompts -Force cannot skip, double prompts, and destructive cmdlets with no gate. Use when reviewing a change to a destructive cmdlet, or to sweep a folder under src/Commands/.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All of this is decidable from the source, across every cmdlet.

    line 18
  2. Very specific:

    every ShouldProcess( and ShouldContinue( call the cmdlet can reach

    line 31
  3. Very specific:

    Search for SupportsShouldProcess, ShouldProcess(, ShouldContinue( and SwitchParameter WhatIf across the scope to build the candidate list.

    line 66
  4. Distinctive:

    Read each candidate class, and the helpers it delegates to, before classifying it.

    line 68

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Playbook: whatif-audit

Find cmdlets whose -WhatIf, -Confirm or -Force does not do what it promises.

Why

A user runs Remove-PnPSomething -WhatIf to see what would happen. If the cmdlet declares SupportsShouldProcess and never calls ShouldProcess, PowerShell accepts the switch and the cmdlet deletes the object anyway. Nothing in the build catches this, and the user finds out in their tenant. A prompt that -Force cannot skip is the same kind of defect for automation: the script hangs, or fails, in a pipeline with nobody there to answer.

All of this is decidable from the source, across every cmdlet.

Read-only. Report findings in the session. Never open an issue or PR for one — see Human in the loop.

The rules themselves are in dotnet-standards under Safety. This playbook is the sweep.

What to collect per cmdlet

Resolve each cmdlet through its [Cmdlet(...)] attribute, not its filename. For each one, record:

  • SupportsShouldProcess and ConfirmImpact on the attribute
  • every ShouldProcess( and ShouldContinue( call the cmdlet can reach
  • whether it has a Force parameter, and where that parameter is read
  • any parameter the class itself declares named WhatIf or Confirm

Follow the delegation before reporting. Some cmdlets gate inside a helper they call rather than in their own class: recycle bin utilities, the copy and move proxy cmdlets, and callbacks passed to utility classes. A cmdlet that hands this or a callback to a helper is not a finding until you have read the helper. Check whether src/Commands/Base/BasePSCmdlet.cs defines gate helpers of its own, and count a call to one of them as a call to ShouldProcess.

Findings, most serious first

KindWhat it isWhat the user gets
whatif-ignoredSupportsShouldProcess = true, and no reachable ShouldProcess call-WhatIf performs the operation
force-bypasses-whatifForce || ShouldProcess(...)-Force -WhatIf performs the operation
hand-rolledThe class declares its own WhatIf or Confirm parameter-WhatIf:$false and $WhatIfPreference do not behave as PowerShell documents
change-before-gateA write, or a CSOM call queued for ExecuteQueryRetry, happens before the gatePart of the change is made under -WhatIf, or after the user answers No
unskippable-promptShouldContinue on a cmdlet with no Force parameter, or one that does not read itAn unattended script waits at a prompt
double-promptShouldProcess and then ShouldContinue on the same path-Confirm asks the same question twice
confirm-unreachableConfirmImpact.None with SupportsShouldProcess-Confirm never prompts
no-gateDestructive verb (Remove, Clear, Reset, Uninstall, Unregister, Disable, Stop) with neither ShouldProcess nor ShouldContinueNo way to preview or confirm
doc-gapSupportsShouldProcess cmdlet whose page has no -WhatIf or -Confirm sectionThe switch is undiscoverable

Force || ShouldContinue(...) is the correct, repository-standard form and is not a finding.

no-gate is an inventory, not a defect list. Many cmdlets in this module have always run without a prompt, and adding one breaks unattended scripts — see api-surface-diff. Report it separately and do not recommend adding a prompt.

Procedure

  1. Scope the run: one cmdlet, a changed file set, a folder under src/Commands/, or the whole repository. State the scope in the report.
  2. Search for SupportsShouldProcess, ShouldProcess(, ShouldContinue( and SwitchParameter WhatIf across the scope to build the candidate list. This sweep needs no shell.
  3. Read each candidate class, and the helpers it delegates to, before classifying it.
  4. For each finding, name the invocation that misbehaves.

Reporting

One row per finding, ordered by the table above:

FieldContent
CmdletVerb-PnPNoun and file.cs:line
KindFrom the table
EvidenceThe attribute and the call, or the missing call
InvocationThe command that misbehaves, and what it does — "Remove-PnPPlannerRoster -WhatIf deletes the roster"
FixThe smallest change, and whether it alters behaviour for a script that works today

You cannot run the cmdlets, so every row is a reading of the code. Say which delegated helpers you read and which you could not resolve.

Finish with counts — cmdlets checked, clean, and findings per kind — so a partial sweep cannot be mistaken for a full one.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.