Document why an automation exists
Code says what a job does; it rarely says why, who owns it, or what breaks if it stops. A short, explicit record next to the job prevents the next reader from guessing — or deleting the wrong thing.
Procedure
- Put a header block at the top of the job's entry file, or a sibling
JOB.md, with fixed fields: # JOB: nightly-reconcile why: detect drift between ledger and gateway settlements owner: payments-oncall (see CODEOWNERS) trigger: cron 03:00 UTC, concurrencyPolicy Forbid input: gateway_settlements, ledger_entries (last 36h) output: reconciliations table; alert on drift > 0.01% blast_radius: insert/update only; never deletes runbook: https://wiki/runbooks/nightly-reconcile retire_when: gateway retires the settlement feed (Q3 2027) - State the why as the failure it prevents: "catches stuck settlements", not "runs a SQL join".
- Name the owner as a rotation or role, not an individual, and point at where ownership is recorded.
- State the blast radius explicitly: what it can read and write, and whether it is reversible. This is the field reviewers forget to check.
- Record the
retire_whencondition so the job has an end-of-life, not just a start. - Keep the doc next to the code so a change to the job lands in the same review as the doc.
- Add a lint or CI check that the header's required fields exist, so a new job cannot ship undocumented.
- Link the runbook and the alert rules so the reader can find operational context in one hop.
- Update the doc when the trigger or output changes; a stale header is worse than none because it is trusted.
- For config-as-code jobs, store the doc as metadata in the same object so the schedule and the why travel together.
Pitfalls
- A doc that restates the code ("it reads rows and writes rows") instead of the purpose.
- Ownership that names someone who left two teams ago.
- No blast radius field, so a reviewer cannot judge the risk of a change.
- Docs in a wiki disconnected from the code, drifting apart within a month.
- A purpose so vague ("maintenance") that it justifies anything.
- No end-of-life condition, so the job has no natural retirement path.
Verification
for f in jobs/*/JOB.md; do grep -qE '^(why|owner|trigger|blast_radius|runbook):' "$f" || echo "MISSING $f"; done
# pass: prints nothing; every live job has the required header fields
Report the header fields, the owner, the blast radius, and the retire_when condition for the job in question.