# 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 (`vps` project), 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 → `STOP` and 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.

## References

- [`docs/agents/issue-tracker.md`](../docs/agents/issue-tracker.md)
- [`RUNBOOKS.md`](../RUNBOOKS.md)