Explain and Risk-Flag Inherited Scripts

Tier: Core · Workflow area: Scripting & automation · ~30 minutes per script

This playbook is the safe procedure for inherited automation: paste the script, extract a structured explanation and risk flags, then verify the explanation empirically in a sandbox VM — because an AI misreading of legacy code is exactly as dangerous as the legacy code itself.

When to use

• Taking over an estatenew job, new client, departed colleague; the scheduled-task list is full of scripts with no author and no docs.
• Before modifying anything legacya "small change" to a script you don't understand is how outages are born; explanation precedes edits.
• Audit and cleanup drivesdeciding which of 60 inherited automations to keep, rewrite or retire (pairs with pb-25's documentation sweep).

When NOT to use

• On scripts you suspect are malicious. Odd persistence, obfuscation, encoded blobs: that is a security-incident artifact, not a refactoring candidate — hand it to security with hashes intact, do not run it anywhere.
• To skip the sandbox. If your plan is explanation-then-straight-to-prod-edit, stop; the sandbox run is the playbook, not an optional garnish.
• On thousand-line application codebasesthis recipe targets ops scripts; a legacy application deserves proper repo tooling and code-review workflows, not a paste.

The recipe

1. 1.

   Capture before you touch. Copy the script and note its execution context: what account runs it, from where, on what schedule, and what its last run status was. Context determines blast radius:

   Copy

   Get-ScheduledTask | Where-Object {$_.Actions.Execute -match "powershell"} |
     Select-Object TaskName, @{n="RunAs";e={$_.Principal.UserId}},
       @{n="Command";e={$_.Actions.Arguments}} | Format-List
   

2. 2.

   Run the explanation prompt.

   Copy

   Explain this inherited PowerShell script for the admin who now owns
   it. Nobody on the team knows what it does.
   
   Output:
   1. One-paragraph summary: purpose, inputs, outputs, systems touched.
   2. Annotated walkthrough by section: what each block does, in order.
   3. RISK FLAGS — list each with line numbers:
      - destructive operations (delete/overwrite/disable) and their scope
      - hardcoded credentials, paths, hostnames, IPs
      - error handling gaps (what happens when step X fails?)
      - assumptions about environment that may no longer hold
      - anything you cannot confidently explain — mark as OPAQUE
   4. Dependencies: modules, files, network shares, other scripts.
   5. Blast radius if run right now, as-is, in the wrong context.
   
   Do not propose changes yet. Script: [paste]
   

   The OPAQUE marker matters: a model that must explain everything will fabricate purpose for genuinely weird code. Sample flag output you should expect:

   Copy

   RISK FLAGS
   - Line 118: Remove-Item -Recurse -Force on path built from
     $env:BACKUPROOT + unvalidated date string — if BACKUPROOT is
     unset, path becomes "\2026-08" relative to CWD. Destructive.
   - Line 203: plaintext SQL credentials ("svc_backup / Summ3r...")
   - Lines 240–280: OPAQUE — COM automation against "SDK.Helper",
     object not resolvable from script contents.
   

3. 3.

   Verify the explanation in a sandbox. Spin a throwaway VM (or container for non-Windows), stub the dependencies (fake the network share as a local folder, point at a test tenant, empty the credential), and run with -WhatIf where supported plus full transcript. You are testing the explanation: does the script actually do what the model said? Divergence means the annotation is wrong — iterate before trusting either.

4. 4.

   Chase the OPAQUE blocks empirically. For each opaque section, add temporary logging around it in the sandbox, run, and inspect. Feed the observed behavior back: "This block, when run, wrote these registry keys: [paste] — now explain it." Observation converts opaque to explained; guessing does not.

5. 5.

   Produce the risk register and decision. For each flagged risk: severity, exploit/failure scenario, and one of three verdicts — fix now (hardcoded credentials always land here), fix in rewrite, accept with note. Then the script-level decision: keep as-is with docs, harden in place, rewrite (via pb-21's protocol), or retire.

6. 6.

   Ask for the modernization plan — scoped by your decision. "Given this script and these risk flags, propose a modernization plan: minimal hardening changes first (credentials to SecretManagement, error handling, logging), then a rewrite outline in modern idioms with -WhatIf support. Separate the two — I may only do the first." Keeping hardening separate from rewrite is what makes the plan executable this sprint instead of never.

7. 7.

   Document while it is fresh. The explanation, risk register, and execution context go into a runbook page next to the script (pb-25's format). The next inheritor gets an explained script; the chain of fear ends with you.

Make it yours

• Bash/Python legacyidentical flow; ShellCheck/pylint add mechanical flags before the LLM pass, and containers make cheaper sandboxes than VMs.
• Vendor-supplied scriptsthe ones your RMM or a vendor installed years ago: explanation is legitimate, but check support terms before modifying; often the right verdict is "document + monitor, replace with current vendor version."
• Batch triage at estate-takeover scalefirst pass, run only steps 1–2 across everything (summary + risk flags only), rank by blast radius, then deep-dive the top ten with the full recipe.

Quality check

• Explanation verified, not admired. At least one sandbox run comparing predicted vs. actual behavior — the model explaining code it has misread is this playbook's core failure mode.
• Line numbers in every flag. A risk flag you cannot jump to is a rumor; regenerate with line references or renumber the paste.
• Credentials found = credentials rotated. A plaintext credential discovered in an inherited script is compromised by definition of unknown history — rotate it, don't just relocate it.
• The scheduled task keeps running until the decision is made. Do not stop the mystery job as step one — half of these scripts hold something important up; understand, then decide.