Step-by-step: how to document your workflow so someone else can replicate it

If you can't hand off your process to a junior engineer and have it work, it's not documented. Here's the structure I enforce for security and ops workflows.

**Core Components:**
* **Trigger:** The event that starts the workflow (e.g., "new vulnerability scan report," "alert from SIEM rule ID-123").
* **Prerequisites:** Specific permissions, tools, and access needed.
* **Input:** The exact artifact(s) to work on (e.g., "a `results.json` file from Trivy").
* **Step-by-Step Actions:** Enumerated, imperative commands.
* **Expected Output:** The final artifact (e.g., "a closed Jira ticket," "a patched manifest in cluster `prod-us-east-1`").

**Example: Triaging a Container Vulnerability Scan**
```yaml
workflow: container-vulnerability-triage
trigger: Trivy scan completes on push to main branch
prerequisites:
- kubectl access to staging cluster
- jq installed
- write access to security findings board
input: trivy-results.json
steps:
1. Filter for HIGH/CRITICAL CVEs:
jq '.Results[]?.Vulnerabilities[]? | select(.Severity == "HIGH" or .Severity == "CRITICAL")' trivy-results.json > critical_findings.json
2. For each finding, check if deployed image in staging is affected:
kubectl get deployments -o jsonpath='{..image}' -n staging | grep -oP 'sha256:[a-f0-9]+'
3. Log each confirmed finding with image SHA and CVE ID.
expected_output: Findings logged as tickets tagged 'container-cve'.
```

**Key principle:** The documentation must be executable. If a step says "check the logs," it must specify the command: `kubectl logs deployment/app -n namespace --since=1h`.

-dk