SOTA Docs & Engineering Workflow

Purpose

Expert-level rules for the artifacts around the code: documentation (structure, reference, freshness, runbooks) and the collaboration workflow (PRs, review, commits, releases). These are the highest-leverage, lowest-glamour practices — review latency and doc decay quietly dominate team throughput. Rules are imperative with rationale and good/bad examples; every rules file ends with an audit checklist. Load only the files relevant to the task via the index below.

Boundaries: ADR practice lives in sota-architecture; API contract design in sota-api-design; tag signing/provenance and CI supply chain in sota-devsecops. This skill references them rather than repeating them.

BUILD mode

When creating docs or setting up workflow:

1. Classify before writing. Every doc is exactly one Diátaxis mode

(tutorial / how-to / reference / explanation) and is titled accordingly; mixed-mode pages are the defect to design out (rules/01 §1).

1. Docs live with the code: in-repo, PR-reviewed, CI link-checked, examples

executed. If a doc can't change in the same PR as the code, it will decay (rules/01 §2, §4).

1. README = what / why / 5-minute quickstart / honest status, then links

out (rules/01 §3). Runbooks are alert-linked and command-exact (rules/01 §5).

1. Reference is generated from OpenAPI/docstrings/rustdoc/godoc with

warnings-as-errors; doc comments carry the why, contract, and failure modes; examples run in CI (rules/02 §1–4).

1. Changelog from day one: Keep a Changelog format, Unreleased section

updated in the PR that makes the change, user-impact language (rules/02 §6).

1. Workflow defaults: small single-purpose PRs with what/why/how-tested

descriptions (rules/03 §1–2); trunk-based short-lived branches; atomic commits with imperative ≤72-char subjects; conventional commits only if automation consumes them (rules/04 §1–3).

1. Agent docs: one short, human-curated AGENTS.md/CLAUDE.md with exact

commands and repo-specific traps — never auto-generated bloat (rules/01 §7).

1. Before declaring done, self-review against the relevant files' **Audit

checklists**.

AUDIT mode

When auditing docs or workflow:

1. Scope the surfaces: docs tree + README + runbooks (rules/01), generated

reference + changelog + migration guides (rules/02), recent PRs and review threads (rules/03), git history, branches, and tags (rules/04).

1. Audit reality, not policy. Sample artifacts: run the quickstart on a

clean environment, follow a runbook's commands, read 10 docstrings, read the last 20 merged PRs and 50 commits, diff a recent minor release for breaking changes. A CONTRIBUTING.md full of rules nobody follows is itself a finding.

1. Work through each loaded file's Audit checklist; probe the classic gaps:

tutorial that fails partway, stale docs contradicting code, README quickstart requiring tribal knowledge, alert with no runbook, default: Error as the only documented failure, changelog that's a commit dump, 2,000-line rubber-stamped PRs, force-push during review, broken commits on main, moved release tags, gitflow on a continuous-deploy service.

Severity conventions

• Critical — actively dangerous artifacts: runbook whose commands are wrong

or destructive without warning; docs instructing insecure practice (secrets in config examples, auth bypass); moved/deleted published release tag; breaking change shipped in a minor/patch with no notice; merge to default branch with no review or required checks at all.

• High — reliably costs incidents or releases: page-able alerts without

runbooks; quickstart/tutorial that fails; published docs contradicting current released behavior; no changelog or migration guide across breaking releases; review rubber-stamping (large PRs, instant LGTMs, AI volume merged unread); non-bisectable main (broken commits); releases built outside CI.

• Medium — erodes trust and throughput: mixed Diátaxis modes; undocumented

public symbols or name-restating docstrings; unexecuted doc examples; no link-checking; PR descriptions missing why/how-tested; review SLA routinely blown; long-lived feature branches; commit-dump changelog; conventional commits adopted without enforcement or automation.

• Low — polish: missing freshness dates; vanity/stale badges; unlabeled

nit comments; subject lines over 72 chars; missing .git-blame-ignore-revs for reformat commits; docs index drift.

Finding format

[SEVERITY] <one-line title>
Where: <file:line | doc URL | PR/commit ref | branch/tag>
Rule: <rules-file §section>
Issue: <what is wrong, with observed evidence (quote the doc/PR/commit)>
Impact: <concrete consequence — who is misled, what breaks, what it costs>
Fix: <specific change; corrected text/command/process where load-bearing>

Order by severity; one finding per root cause; every finding cites sampled evidence (a doc you executed, a PR you read) — no findings from vibes.

Rules index

Top-10 non-negotiables

1. One Diátaxis mode per document — tutorials teach, how-tos accomplish,

reference informs, explanation contextualizes; titles declare which. (rules/01 §1)

1. Docs are code: in-repo, PR-reviewed, link-checked in CI; behavior

changes update docs in the same PR. (rules/01 §2)

1. Wrong docs are worse than none — own every doc, date-review the

operational ones, delete stale pages instead of archiving them. (rules/01 §4)

1. Every page-able alert links to a command-exact, incident-tested runbook.

(rules/01 §5)

1. **Reference generated from source with undocumented-public-symbol as a build

failure; doc examples compile and run in CI.** (rules/02 §1–3)

1. Document failure modes: every operation states what can fail and what

the caller should do; error messages point toward the fix. (rules/02 §4)

1. **Changelog in Keep a Changelog form, written in user-impact language,

updated in the PR — and breaking changes ship with a migration guide after a deprecation period.** (rules/02 §6–7)

1. **Small, single-purpose PRs with what/why/how-tested descriptions; first

review response within one business day.** (rules/03 §1–3)

1. The review bar is provenance-blind: AI-generated code gets the same

scrutiny, and style/lint/type findings are CI's job, never a human's. (rules/03 §6–7)

1. **Main is always green and bisectable; published tags are immutable;

version numbers keep SemVer's promises with breaking changes announced before they're shipped.** (rules/04 §1, §4–5)