Documentation gate decisions

Updated Jul 18, 2026

When a change reaches continuous integration (CI), the workflow decides whether documentation validation is required and whether Mermaid diagram validation should also run. The decision is based on the changed-file list, whether any documentation-tooling configuration changed, and, for Markdown files, whether the current file contents contain Mermaid diagrams.

Figure 1. Accessible flow diagram showing how the CI policy decides whether the documentation gate and Mermaid validation are required from the changed-file list, including the conservative fallback path used when the list is empty or malformed.

Yes

No

Yes

No

Yes

No

Yes

No

Start
Receive_changed_file_list

Validate_input_list

List_empty_or_malformed?

Apply_safe_default_policy

Classify_changes_by_path

Only_documentation_inputs_changed?

Set docs_gate_required = true

Mixed_or_code_only_changes

Any_documentation_inputs_changed?

Set docs_gate_required = false

Mermaid_or_conservative_path?

Set nixie_required = true

Set nixie_required = false

Emit_policy_output
with_safe_defaults

End
Workflow_consumes_flags

In practice, the current policy behaves as follows:

  • If the changed-file list is unavailable, CI runs both the documentation gate and Mermaid validation as a safe default.
  • If no documentation inputs changed, the documentation gate is skipped.
  • If Markdown files changed, the documentation gate runs.
  • If documentation-tooling configuration changed, the documentation gate and Mermaid validation both run as a conservative default.
  • Mermaid validation runs only when one of the changed Markdown files contains a Mermaid diagram, or when the workflow takes that conservative fallback.

The CI workflow publishes these decisions as stable flags so the docs-gate job can stay required even when it skips documentation-specific work. When the workflow takes the conservative Mermaid path because a file could not be read, it also publishes which files triggered that fallback.