git:20260626.8c3a035 to git:20260716.e4afc80

---

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

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)