# Operations procedure (docs/operations/{procedure}.md)

Truth document. Use for: any **recurring** procedure — development, deployment, maintenance. The one-time first run (prerequisites, install, env files, first commands, the stack) is not one of these: it has its own template and a fixed name, `templates/setup.md` → `docs/operations/setup.md`, one per repo. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.

A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **migration runbook** (record, `templates/migration-runbook.md`). The test: will someone run this again next month? Yes → operations. No → runbook.

Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubleshooting, Rollback — include only when they carry real content.

If a procedure is a deterministic command list run frequently, script it and have the doc point at the script — a doc should carry judgment (when, why, what to check), not replace automation.

```markdown
---
type: operations
description: "{at most 300 characters: what this document settles and where its boundary sits}"
---

# {Procedure Name}

**Goal:** What this procedure accomplishes, one line.

## Preconditions

- Access, tools, or state required before starting — exact versions, env vars, credentials location

## Steps

1. One action per step, exact command in a code block
2. Note expected output where it disambiguates success from failure

## Verification

- The observable end state that confirms it worked — exact check commands, not "it should work now"

## Troubleshooting

- Symptom → cause → fix (append entries as failures are root-caused)

## Rollback

- How to undo, and when undo stops being possible
```