docs(capabilities): add worked example for checking GHA workflow statuses

src/capabilities/github.md

@@ -38,10 +38,10 @@ If Sam catches itself proposing something without having looked at how it's used
 
 ## Bounding Git Diff, Show, and Log Outputs
 
-To avoid context window overflows and Vertex `400 INVALID_ARGUMENT` crashes, Sam never reads unconstrained raw `git diff`, `git show`, or log outputs into context. When dealing with branches or commits that contain large changes, compiled assets, schema snapshots, translation catalogs (`*.po`), or JSON synchronizations:
+To avoid context window overflows and Vertex `400 INVALID_ARGUMENT` crashes, Sam never reads unconstrained raw `git diff`, `git show`, or `git log -p` outputs into context. When dealing with branches or commits that contain large changes, compiled assets, schema snapshots, translation catalogs (`*.po`), or JSON synchronizations:
 
-- **Check size first:** Use `git diff --stat` or `git show --stat` to see which files changed and their relative sizes first.
-- **Filter files:** Restrict the diff or show command to specific code files or directories (e.g. `git diff origin/main -- <path>` or `git show <commit> -- <path>`).
+- **Check size first:** Use `git diff --stat`, `git show --stat`, or `git log --stat` first to see which files or commits changed and their relative sizes.
+- **Filter files:** Restrict the diff, show, or log command to specific code files or directories (e.g. `git diff origin/main -- <path>`, `git show <commit> -- <path>`, or `git log -p -- <path>`).
 - **Exclude generated files:** Use git pathspec exclusions to filter out massive generated files, translation files, schema snapshots, and package lockfiles (e.g. `git diff origin/main -- . ':!*.json' ':!*lock.json' ':!*.po'`).
 - **Cap lines:** If the output is still potentially large, pipe it through a cap (e.g. `head -n 500` or `head -c 50000`) or use a worker to summarize the changes.
 
@@ -67,3 +67,17 @@ When fixing CI or making edits on external repositories (such as `Dembrane/echo`
 - **Rely on remote CI for validation:** Fix the code, push the branch, and let the target repo's GitHub Actions or CI environment run the linters, type-checkers, and test suites.
 - **Do not install heavy tooling locally:** Do not install heavy linting, type-checking, or testing packages (`mypy`, `ruff`, etc.) or run full test suites inside Sam's own container to pre-check external repos. This burns session budget on package installation and is prone to environment-related timeouts.
 - **Exception for local checks:** Only run lightweight checks locally if those tools are already installed and active in Sam's container. Never run heavy testing or installation cycles locally for an external repo when the target repo's CI is available to validate.
+
+## Worked Example: Checking GHA Workflow and Deploy Statuses
+
+When a PR is merged or pushed, a deployment or test workflow is triggered in GitHub Actions. Sam can monitor the progress of these workflows directly from the container session using the `gh` CLI:
+
+```bash
+# 1. List the most recent workflow runs on a branch (e.g. main)
+gh run list --repo Dembrane/sam --branch main --limit 3
+
+# 2. View details of a specific workflow run to check job status and logs
+gh run view <run_id> --repo Dembrane/sam
+```
+
+This ensures we verify that the automated deployments or checks complete successfully without guessing.