| 1 | # CMD Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | Dedicated playbook for Windows CMD/batch automation in legacy and compatibility scenarios. |
| 5 | |
| 6 | ## Scope |
| 7 | - Batch reliability constraints |
| 8 | - Quoting and variable expansion pitfalls |
| 9 | - Errorlevel-based control flow |
| 10 | - Safe interop with modern tooling |
| 11 | |
| 12 | ## Evidence-Based Working Format |
| 13 | - Fact: describe concrete batch failure or compatibility requirement. |
| 14 | - Hypothesis: define smallest batch change to resolve it. |
| 15 | - Check: run deterministic test scenario with explicit outputs. |
| 16 | - Decision criterion: predefined success/failure threshold. |
| 17 | - Confidence mark: explicit certainty level. |
| 18 | |
| 19 | ## Core Contracts |
| 20 | - Use CMD only when compatibility requires it. |
| 21 | - Keep quoting explicit for all file paths. |
| 22 | - Validate delayed expansion behavior before rollout. |
| 23 | - Keep control flow readable and deterministic. |
| 24 | |
| 25 | ## Error Contracts |
| 26 | - Use `if errorlevel` checks consistently. |
| 27 | - Preserve exit code semantics for calling processes. |
| 28 | - Avoid fall-through behavior in failure branches. |
| 29 | - Surface command failure context in logs. |
| 30 | |
| 31 | ## Project-Aware Contracts |
| 32 | - Resolve target directory before write operations. |
| 33 | - Guard destructive commands with explicit target confirmation. |
| 34 | - Keep environment assumptions documented. |
| 35 | - Prefer wrapper scripts when orchestration complexity grows. |
| 36 | |
| 37 | ## Interop Contracts |
| 38 | - Be explicit when invoking PowerShell, Bash, Python, or Docker from CMD. |
| 39 | - Normalize return-code handling at boundaries. |
| 40 | - Keep encoding and locale behavior visible when parsing text outputs. |
| 41 | - Minimize fragile parsing of tool output strings. |
| 42 | |
| 43 | ## Metrics |
| 44 | - Success rate in legacy automation flows. |
| 45 | - Incidents caused by quoting or delayed expansion. |
| 46 | - Time to diagnose `errorlevel` control-flow failures. |
| 47 | - Frequency of CMD-specific regressions after changes. |
| 48 | |
| 49 | ## Revisit Triggers |
| 50 | - Rising maintenance cost of batch scripts. |
| 51 | - Repeated interop issues with modern toolchain. |
| 52 | - Frequent regressions from environment drift. |
| 53 | |
| 54 | |