| 1 | # Windows Environments Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | Project-independent playbook for reliable engineering and troubleshooting on Windows hosts. |
| 5 | |
| 6 | ## Scope |
| 7 | - Windows process/service runtime behavior |
| 8 | - Security and identity context |
| 9 | - Filesystem and path semantics |
| 10 | - Operational diagnostics baseline |
| 11 | |
| 12 | ## Evidence-Based Working Format |
| 13 | - Fact: capture concrete host symptom (startup failure, permission denial, runtime instability). |
| 14 | - Hypothesis: define smallest plausible Windows-level cause. |
| 15 | - Check: run minimal reproducible verification command set. |
| 16 | - Decision criterion: predefine close/escalate threshold. |
| 17 | - Confidence mark: explicit certainty and residual risk. |
| 18 | |
| 19 | ## Core Windows Contracts |
| 20 | - Service account and token context must be explicit. |
| 21 | - UAC/policy boundaries must be validated for privileged actions. |
| 22 | - Path and file-lock assumptions must be explicit. |
| 23 | - Encoding and locale expectations must be declared. |
| 24 | |
| 25 | ## Runtime and Service Contracts |
| 26 | - Service lifecycle, dependencies, and startup policy must be deterministic. |
| 27 | - Startup arguments and environment variables must be explicit. |
| 28 | - Failure actions and restart policy must be intentional, not default. |
| 29 | - Background workers must support graceful stop/restart. |
| 30 | |
| 31 | ## Security and Identity Contracts |
| 32 | - Verify execution identity before diagnosing application logic. |
| 33 | - Validate ACL ownership and inheritance on critical paths. |
| 34 | - Keep credential scope minimal and auditable. |
| 35 | - Separate interactive-user assumptions from service-host reality. |
| 36 | |
| 37 | ## Shell Context Contract (Git and Tooling) |
| 38 | - Distinguish shell families explicitly: `PowerShell/cmd`, Git Bash (MSYS/MinGW), WSL. |
| 39 | - Assume config visibility can differ across shell families until proven otherwise. |
| 40 | - For author/identity incidents, verify in the active shell: |
| 41 | - `git config --show-origin --get user.name` |
| 42 | - `git config --show-origin --get user.email` |
| 43 | - `git var GIT_AUTHOR_IDENT` |
| 44 | - Check process environment overrides in the active shell: |
| 45 | - `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL`, `EMAIL`. |
| 46 | - Prefer native Windows shell for canonical repo operations unless cross-shell behavior is intentionally required. |
| 47 | |
| 48 | ## Filesystem and IO Contracts |
| 49 | - Normalize paths and quote paths with spaces. |
| 50 | - Model file-sharing/locking behavior explicitly. |
| 51 | - Keep mutation boundaries explicit for automation scripts. |
| 52 | - Detect long-path and permission edge cases early. |
| 53 | |
| 54 | ## Diagnostics Baseline |
| 55 | - Event Viewer + structured application logs. |
| 56 | - Process/resource counters and service status checks. |
| 57 | - Startup/failure timeline reconstruction from host evidence. |
| 58 | - One concise root-cause and prevention delta per incident. |
| 59 | |
| 60 | ## Metrics |
| 61 | - Mean time to identify Windows host root cause. |
| 62 | - Frequency of service-account/ACL-related incidents. |
| 63 | - Startup failure recovery time. |
| 64 | - Reopen rate for Windows environment incidents. |
| 65 | |
| 66 | ## Revisit Triggers |
| 67 | - Repeat incidents caused by identity/policy mismatch. |
| 68 | - Frequent path/locking regressions. |
| 69 | - Service instability with unclear host-level ownership. |
| 70 | |
| 71 | |