| 1 | # Bash Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | Dedicated playbook for Unix shell scripting with predictable behavior and portability discipline. |
| 5 | |
| 6 | ## Scope |
| 7 | - Shell safety and strictness |
| 8 | - Portability and POSIX boundaries |
| 9 | - Script composition and process control |
| 10 | - Reliability in CI and local workflows |
| 11 | |
| 12 | ## Evidence-Based Working Format |
| 13 | - Fact: identify concrete shell failure or nondeterministic behavior. |
| 14 | - Hypothesis: define smallest change that should stabilize behavior. |
| 15 | - Check: validate in minimal reproducible shell scenario. |
| 16 | - Decision criterion: explicit close/escalate threshold. |
| 17 | - Confidence mark: explicit certainty level. |
| 18 | |
| 19 | ## Core Contracts |
| 20 | - Use strict mode where applicable (`set -euo pipefail`). |
| 21 | - Quote variables defensively. |
| 22 | - Keep inputs explicit; avoid hidden environment coupling. |
| 23 | - Prefer small composable scripts over long monoliths. |
| 24 | |
| 25 | ## Portability Contracts |
| 26 | - Define target shell (`bash` vs POSIX `sh`) explicitly. |
| 27 | - Avoid bash-specific features when portability is required. |
| 28 | - Keep tool dependencies explicit (`awk/sed/grep` variants matter). |
| 29 | - Validate behavior on representative runtime environments. |
| 30 | |
| 31 | ## Process and Pipeline Contracts |
| 32 | - Preserve meaningful exit codes through pipelines. |
| 33 | - Avoid subshell surprises with stateful variables. |
| 34 | - Keep temporary file lifecycle explicit and safe. |
| 35 | - Make retries explicit for network-bound operations. |
| 36 | |
| 37 | ## Project-Aware Contracts |
| 38 | - Resolve repo root before mutating operations. |
| 39 | - Keep destructive paths guarded and explicit. |
| 40 | - Include dry-run mode for mass operations. |
| 41 | - Record required tools and versions in script headers. |
| 42 | |
| 43 | ## Metrics |
| 44 | - Script reproducibility across environments. |
| 45 | - Pipeline failure diagnosis time. |
| 46 | - Frequency of quoting/expansion defects. |
| 47 | - Local/CI behavior divergence rate. |
| 48 | |
| 49 | ## Revisit Triggers |
| 50 | - Repeat failures from shell option misunderstandings. |
| 51 | - Environment-specific behavior drift. |
| 52 | - Increase in brittle one-liner dependencies. |
| 53 | |
| 54 | |