/sota-docs-workflow

name: sota-docs-workflow
description: >-
  State-of-the-art documentation and engineering-collaboration guidance (2026)
  covering documentation architecture (Diátaxis, docs-as-code, READMEs,
  runbooks, onboarding, AI-readable docs), API/reference docs and changelogs,
  and the team workflow around code: pull requests, code review conduct,
  commit discipline, branching, and releases. Use when writing or structuring
  any documentation AND when auditing docs quality, and when designing or
  auditing collaboration workflow. Not for in-product UI microcopy (use
  sota-ux-writing) or marketing/landing-page copy (use sota-copywriting).
  Trigger keywords: documentation, docs,
  README, API docs, docstring, changelog, release notes, migration guide,
  code review, pull request, PR description, commit messages, conventional
  commits, branching, semver, onboarding, runbook, AGENTS.md, llms.txt,
  spec-driven development, SDD, Spec Kit, Kiro, specification, acceptance
  criteria, steering files.

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). 2. **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). 3. **README = what / why / 5-minute quickstart / honest status**, then links out (`rules/01` §3). Runbooks are alert-linked and command-exact (`rules/01` §5). Ship the **documentation baseline** — README + LICENSE + CHANGELOG always; SECURITY/CONTRIBUTING/CODE_OF_CONDUCT once public — each with one canonical home, not scattered copies (`rules/01` §8). 4. **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). 5. **Changelog from day one**: Keep a Changelog format, `Unreleased` section updated in the PR that makes the change, user-impact language (`rules/02` §6). 6. **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). 7. **Agent docs**: one short, human-curated AGENTS.md/CLAUDE.md with exact commands and repo-specific traps — never auto-generated bloat, never a restatement of ambient/global rules (`rules/01` §7, §10). On a **new repo**, `.gitignore` + secret scanning and LICENSE land before the first commit (`rules/01` §10). 8. **Solved failures accrue** in a symptom-keyed troubleshooting playbook, written in the PR that fixed them (`rules/01` §9). 9. 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`). 2. **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. 3. 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; subj