sota-docs-workflow git:20260716.e4afc80A

Immutable. This exact content is served forever at /api/v1/blob/6953b26dcb48e878.

---
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).
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
   (`rules/01` §7).
8. 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; 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

| File | Read this when... |
|---|---|
| `rules/01-documentation-architecture.md` | Writing/structuring/auditing any docs: Diátaxis modes, docs-as-code CI (link checks, doc tests), README front-door, decay control (ownership, freshness, aggressive deletion), runbooks, onboarding docs, discoverability, AGENTS.md/CLAUDE.md and llms.txt. |
| `rules/02-api-reference-changelogs.md` | API/library reference docs: generation from source (OpenAPI/docstrings/rustdoc/godoc), docstring content (why/contract/failures), runnable examples and doctests, error documentation, versioned docs, Keep a Changelog discipline, migration guides. |
| `rules/03-code-review-pr-workflow.md` | PR and review process: PR sizing and slicing, description discipline (what/why/how-tested), review SLAs and WIP limits, reviewer/author conduct, blocking vs non-blocking comments, draft and stacked PRs, automation boundaries, reviewing AI-generated code. |
| `rules/04-commits-branches-releases.md` | Git history and shipping: atomic/bisectable commits, message discipline, Conventional Commits and when they pay, trunk-based vs gitflow honesty, SemVer semantics, breaking-change pipeline, tag immutability, release notes vs changelog, release automation. |
| `rules/05-spec-driven-development.md` | Driving non-trivial/agent-built work from a living spec: the intent→plan→tasks→implement→verify loop, separating what from how, testable acceptance criteria, `[NEEDS CLARIFICATION]` markers, specs-in-repo and spec-drift control, steering/constitution vs per-feature specs, linking ADRs/OpenAPI instead of copying, and when SDD is overhead. Pairs with `sota-testing` rules/08 (executable acceptance). |

## 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)
2. **Docs are code**: in-repo, PR-reviewed, link-checked in CI; behavior
   changes update docs in the same PR. (rules/01 §2)
3. **Wrong docs are worse than none** — own every doc, date-review the
   operational ones, delete stale pages instead of archiving them. (rules/01 §4)
4. **Every page-able alert links to a command-exact, incident-tested runbook.**
   (rules/01 §5)
5. **Reference generated from source with undocumented-public-symbol as a build
   failure; doc examples compile and run in CI.** (rules/02 §1–3)
6. **Document failure modes**: every operation states what can fail and what
   the caller should do; error messages point toward the fix. (rules/02 §4)
7. **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)
8. **Small, single-purpose PRs with what/why/how-tested descriptions; first
   review response within one business day.** (rules/03 §1–3)
9. **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)
10. **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)