| 1 | # PowerShell Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | Dedicated playbook for reliable Windows-first automation using PowerShell. |
| 5 | |
| 6 | ## Scope |
| 7 | - Object pipeline design |
| 8 | - Command composition and error contracts |
| 9 | - Script safety for repo-aware automation |
| 10 | - Interop with external tools |
| 11 | |
| 12 | ## Evidence-Based Working Format |
| 13 | - Fact: capture failing command behavior or operational friction. |
| 14 | - Hypothesis: define the smallest script change with expected effect. |
| 15 | - Check: run deterministic validation path with explicit outputs. |
| 16 | - Decision criterion: keep/rollback thresholds. |
| 17 | - Confidence mark: explicit certainty level. |
| 18 | |
| 19 | ## Core Contracts |
| 20 | - Prefer object pipeline over fragile string parsing. |
| 21 | - Make path handling explicit and quote paths with spaces. |
| 22 | - Use strict error behavior for production scripts. |
| 23 | - Keep command intent clear with named parameters. |
| 24 | |
| 25 | ## Error and Exit Contracts |
| 26 | - Convert non-terminating errors to explicit failure when needed. |
| 27 | - Surface external command exit codes clearly. |
| 28 | - Avoid silent failures and swallowed exceptions. |
| 29 | - Log enough context to reproduce failures quickly. |
| 30 | |
| 31 | ## Project-Aware Contracts |
| 32 | - Resolve repository/workspace root before write operations. |
| 33 | - Keep mutation boundary explicit in script header. |
| 34 | - Require confirmation or dry-run for destructive operations. |
| 35 | - Record assumptions about tools, environment variables, and permissions. |
| 36 | |
| 37 | ## Interop Contracts |
| 38 | - Distinguish PowerShell-native behavior from external CLI behavior. |
| 39 | - Normalize outputs when chaining with Git/dotnet/docker tools. |
| 40 | - Keep encoding assumptions explicit for file IO and command output. |
| 41 | - Use predictable formatting for machine-consumable outputs. |
| 42 | |
| 43 | ## Metrics |
| 44 | - Automation success rate. |
| 45 | - Mean time to identify failing command. |
| 46 | - Re-run count before successful completion. |
| 47 | - Incidents caused by ambiguous path or quoting behavior. |
| 48 | |
| 49 | ## Revisit Triggers |
| 50 | - Frequent path/quoting regressions. |
| 51 | - Repeat failures from implicit error semantics. |
| 52 | - Growing script complexity without modularization. |
| 53 | |
| 54 | |