windyboyandCursor
343c5db415
Keep sanitized Compose sources in-repo with a confirmation-gated Ansible playbook, add repo-wide validation, tighten runbook ownership/STOP/review metadata, and archive stale research docs. Co-authored-by: Cursor <cursoragent@cursor.com>
94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
# 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; see `RUNBOOKS.md`
|
|
§校验; 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)
|