Docs Quality Gates

Use this checklist in PR review and CI.

1) Language Quality (required)

Disallowed vague language unless explicitly bounded with assumptions:

  • should (unless recommendation with rationale)

  • probably

  • likely

  • usually

  • in theory

  • guaranteed (unless code-enforced invariant)

  • never bricks

Rule: replace with a checkable statement or remove.

2) Evidence Requirement (required)

Every non-trivial behavior claim must include an Evidence section with at least one of:

  • code path + symbol (file.go, function/method name)

  • test name + package

  • generated output path under docs/_generated/test-outputs/

  • reproducible verification command

Preferred format:

Evidence
- Code: edge/relay/executor.go (executeRelay)
- Test: edge/relay/executor_test.go (TestExecutor...)
- Verify: GOWORK=off go test ./edge/relay -run TestExecutor -v

3) How-To-Verify Requirement (required)

Each feature page must include copy/paste commands that verify behavior in a local or CI-equivalent environment.

Minimum:

  • at least one command

  • expected success criteria

  • failure signal (exit code or log/metric mismatch)

4) Config Examples (required)

Config pages must satisfy:

  • examples match current schema and accepted enum values

  • examples include only implemented keys

  • examples pass edged validate --config ...

Recommended validation commands:

GOWORK=off go run ./edge/cmd/edged validate --config ./edge/config/testdata/valid_full.yaml
GOWORK=off go run ./edge/cmd/edged validate --config ./edge/config/testdata/valid_full.toml

5) Naming Consistency (required)

  • structured log event names: dot-delimited (e.g. edge.os.update_detected)

  • Prometheus metrics: underscore-delimited (e.g. edge_os_update_detected_total)

  • capability naming: Edge / edge / edged / edgectl

6) Canonical Source Linkage (required)

This docs repo root (/) is the canonical source for AutonomyOps product and technical truth. Lighter public surfaces — in particular the marketing website at autonomyops.ai — must link to canonical pages rather than restate them. The website is published from the source repo autonomyops/autonomyops.github.io, which is where companion PRs are opened. Full rule: Documentation Standards § Canonical Source.

Reviewer checks:

  • The PR does not duplicate a technical claim, CLI/API reference, configuration detail, or guarantee that already exists in this docs repo. If it does, replace the duplicated content with a link to the canonical page.

  • The PR does not introduce a technical claim into a non-canonical surface (README.md blurbs are summary-only and must point at canonical docs for detail; do not author new behavioral claims directly into the README).

  • If the PR changes a user-visible claim the marketing website (autonomyops.ai) also makes, the PR description names the affected website page(s) and links the companion PR in the website source repo, or states explicitly that none is required (the website does not yet make the claim, or the companion PR has already merged).

A docs-repo PR that changes a user-visible claim without a linked companion PR or a not-required note is blocked on this gate.

7) Docs CI Gates (required)

Run before merge:

make docs-gen
make docs
make docs-lint
make docs-freshness
make docs-coverage-gate-all

Evidence

  • Makefile docs targets

  • scripts/docgen/*

  • scripts/ci/docs-freshness.sh

  • .markdownlint.yml