3.1 KiB
Runbook: issue → mergeable change
Purpose
Turn an approved Linear vps issue into a reviewed, mergeable change in this
repo (docs, runbooks, hosts facts, or Ansible playbooks).
Scope
- Applicable: repo content under
docs/,runbooks/,hosts/,inventory/,ansible/. - Not applicable: mutating production state directly — that goes through
release.md/ansible-operations.md.
Ownership
- Owner: personal ops (Windy)
- Last reviewed: 2026-08-17
- Related systems: Linear MCP (
vpsproject), git
Inputs
| Input | Source | Required | Validation |
|---|---|---|---|
| Issue identifier | Linear (vps project) |
Yes | linear_get_issue <id> returns a description |
| Current repo state | git status / git log |
Yes | Clean or intended worktree |
Safety
- Scope is locked to the issue: do not bundle unrelated changes.
- Never commit secrets (see
AGENTS.md§Safety). - Verify every change; do not merge a change whose verification was skipped.
Procedure
Step 1 — Read the issue
Action — linear_get_issue <id>, read description and acceptance criteria.
Expected — clear scope, action, and verification for the change.
Decision — if the issue is ambiguous or lacks verification criteria, STOP
and ask for clarification (add a needs-info label if applicable). Otherwise go to Step 2.
Step 2 — Inspect and change
Action — read the relevant files, then make the minimal change the issue asks for.
Expected — diff is scoped to the issue.
Decision — if the change needs production mutation, STOP and route to
release.md. Otherwise go to Step 3.
Step 3 — Verify
Action — run scripts/validate-repo.sh from the repo root (covers secret
scan, inventory cross-check, markdown link check, runbook-spec check, and
Ansible --syntax-check); for changes that alter playbook behavior, also run
a read-only ansible-playbook --check where possible.
Verification — scripts/validate-repo.sh exits 0; the concrete checks
must match the change type.
Decision — verification passed → Step 4; failed → Troubleshooting A.
Step 4 — Commit and link
Action — commit with a message containing the full issue ID (e.g. W1N-123: …); open a PR if the change is substantial; link the issue via linear_save_comment.
Verification — git log -1 shows the issue ID; the issue has the commit/PR pointer.
Rollback — git revert <sha> or git checkout <branch> to drop the change; re-verify after.
Troubleshooting
Troubleshooting A — Verification failed
- Evidence: command output, failing check.
- Allowed: fix the change within scope; re-run verification.
- Next: still failing →
STOPand report in the issue.
Final Verification
- Change matches the issue scope.
- Verification passed and the issue is updated with evidence.
Failure Handling
If unfinished: stop, collect the failed check output, record completed steps, and hand back to the issue — do not guess.