| 1 | # Automation Scripting Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | Router playbook for project-aware automation decisions across scripting and container tools. |
| 5 | |
| 6 | ## Scope |
| 7 | - Tool selection by task profile |
| 8 | - Shared safety contracts for all automation |
| 9 | - Evidence-based execution flow |
| 10 | - Links to specialized subdomain playbooks |
| 11 | |
| 12 | ## Evidence-Based Working Format |
| 13 | - Fact: describe current manual burden or failure pattern. |
| 14 | - Hypothesis: state which automation change removes that burden and why. |
| 15 | - Check: run the smallest deterministic scenario. |
| 16 | - Decision criterion: define success/failure threshold before rollout. |
| 17 | - Confidence mark: tag certainty level explicitly. |
| 18 | |
| 19 | ## Project-Aware Global Contracts |
| 20 | - Resolve workspace/repo root explicitly before mutating actions. |
| 21 | - Declare mutation boundary: what can change and what must remain untouched. |
| 22 | - Keep environment assumptions explicit (`required tools`, `required vars`, `required permissions`). |
| 23 | - Make logs actionable and preserve deterministic exit codes. |
| 24 | - Prefer dry-run for bulk/destructive operations. |
| 25 | |
| 26 | ## Tool Selection Matrix |
| 27 | - Use `powershell-playbook.md` for Windows-first automation and object pipelines. |
| 28 | - Use `bash-playbook.md` for Unix/POSIX flows and shell orchestration. |
| 29 | - Use `python-playbook.md` for complex parsing/transformation and reusable logic. |
| 30 | - Use `cmd-playbook.md` only for legacy batch compatibility constraints. |
| 31 | - Use [`../pattern-regex/regex-playbook.md`](../pattern-regex/regex-playbook.md) when matching/parsing logic is core to the task. |
| 32 | - Use `docker-playbook.md` when reproducibility and environment parity are required. |
| 33 | |
| 34 | ## Cross-Tool Safety Rules |
| 35 | - Never run destructive commands against ambiguous target paths. |
| 36 | - Keep quoting/escaping explicit for all paths containing spaces. |
| 37 | - Avoid hidden global state; pass inputs explicitly. |
| 38 | - Include rollback or restore path for stateful operations. |
| 39 | |
| 40 | ## Metrics |
| 41 | - Time saved vs manual process. |
| 42 | - Failure frequency and mean time to recovery. |
| 43 | - Number of reruns needed for successful completion. |
| 44 | - Environment-specific failure rate. |
| 45 | |
| 46 | ## Revisit Triggers |
| 47 | - Frequent manual interventions in scripted flows. |
| 48 | - Rising automation flakiness across environments. |
| 49 | - Repeat incidents caused by wrong tool choice. |
| 50 | - Onboarding friction for running core scripts. |
| 51 | |
| 52 | |