Docs-only Fast Path
When docs-only or generated-only diffs skip validation, and the separate conditions for skipping a docs-only semantic review.
son-of-anton-review (feat/cloudflare-native) classifies paths before validation and model selection. Its “docs-only” label is a filename heuristic, not proof that a change cannot affect runtime behavior. Code, scripts or executable examples under a matching docs path can receive that label too.
What happens on a docs-only PR
- Preflight lists the changed paths with
git diff --name-status origin/<base>...HEAD. - Every path is checked against the doc-like and generated-like matchers.
- With
codeChangesOnlyenabled, docs-only or generated-only diffs skip sandbox validation. Execution policy can skip it independently. - A docs-only review satisfying the semantic-skip conditions below uses a deterministic body instead of the primary semantic model.
- The context graph still builds and appears in preflight context. The deterministic docs-only result leaves
crossRepoImpactempty.
The two classifications are independent, not exclusive. A path such as docs/generated/README.md can match both. When the validation diff-skip applies and both are true, the recorded reason is docs_only.
Classification rules
Classification is deterministic and runs before any model call (src/codex-review-runner.js, isDocLikePath and isGeneratedLikePath).
| Class | Matches | Set when |
|---|---|---|
| Doc-like | A doc, docs, adr, rfc, rfcs, spec or specs directory segment; basename README, CHANGELOG, CONTRIBUTING, SECURITY, DESIGN or ARCHITECTURE with no extension or one dot-free extension; any .md, .mdx, .txt, .rst, .adoc | docsOnly when every changed path matches |
| Generated-like | Any path under dist/, build/, coverage/, generated/, vendor/; any .min.js, .min.css, .lock, .snap | generatedOnly when every changed path matches |
An empty diff is neither. shouldRunValidation is !docsOnly && !generatedOnly. Both flags are emitted on preflight_completed and printed in the preflight summary as Docs-only diff: yes|no and Generated-only diff: yes|no.
The .lock suffix is not a universal lockfile rule. yarn.lock, Cargo.lock and bun.lock match; root package-lock.json, pnpm-lock.yaml and bun.lockb do not match the generated classifier just because they are lockfiles. Dependency-change classification is separate and recognizes those names. A mixed docs/generated diff is not skipped unless all paths satisfy one of the two classes.
Validation skip
When shouldRunValidation is false and codeChangesOnly is on, the runner does not boot a sandbox:
| Event | reason | missingValidations entry |
|---|---|---|
validation_skipped | docs_only | Repo-native install/test/typecheck/lint/build steps were skipped because the diff is docs-only; review focused on contradictions between docs and live code/contracts. |
validation_skipped | generated_only | Repo-native validation was skipped because only generated artifacts changed; inspect the source generator/input change before trusting the artifact output. |
The validation summary line in the review reads SKIPPED repo-native validation: docs-only diff. or SKIPPED repo-native validation: generated-artifact-only diff.
See Validation and Evidence for what runs when the skip does not apply.
Semantic review skip
When the conditions below hold, the primary semantic model is skipped and the runner emits codex_skipped with reason: docs_only. The base deterministic result has:
- Verdict
clear, merge statuscaution, confidence 3. - Overview: "Docs-only change for
<repo>#<pr>at<sha>. Gilf skipped Codex semantic analysis for this automatic run because no runtime code changed." missingValidationsgains: "Codex semantic analysis was skipped because this was an automatic docs-only review."- Merge verdict: "Safe to merge if maintainers agree the documentation matches current runtime behavior."
Generated-only diffs that are not also docs-only skip validation by default but do not trigger this semantic shortcut.
The skip applies only when all of these hold (src/codex-review-runner.js, skipCodexForDocsOnly):
| Condition | Why |
|---|---|
GILF_CODEX_FOR_DOCS_ONLY is not 1 | Setting 1 disables this shortcut |
preflight.docsOnly | Classification above |
No prepared review-memory text (preflight.reviewMemory.text) | Selected stored contexts or memory limitations prevent this shortcut; prior-review history by itself is not this predicate |
| No operator review guidance in the review policy | Custom guidance implies a real pass was requested |
| No manual command on the run | run.command prevents this docs-only shortcut |
| No competitor context | run.competitorContext prevents this docs-only shortcut |
A manual @anton review or @anton rerun prevents the docs-only semantic shortcut. It does not override admission, execution policy, a separately enabled validation-failure shortcut or provider failure. See Triggers and commands.
When the model does run on docs
When a semantic pass runs, the prompt instructs the model to check documentation against current code, tests, configuration, migrations and API behavior, and not invent runtime defects from unchanged code. This is a prompt instruction, not evidence that the model inspected every referenced contract.
Source: the docs-only branch of buildReviewPrompt in src/codex-review-runner.js, and prompts/review-goal-template.md.
Configuration
| Setting | Default | Effect |
|---|---|---|
Repo config validation.codeChangesOnly | true (src/config.js) | Boolean false disables diff-based validation skipping when not overwritten by worker defaults |
GILF_VALIDATION_CODE_CHANGES_ONLY | on (src/validation-config.js) | Exact string false sets the worker value to false; 0 does not |
GILF_CODEX_FOR_DOCS_ONLY | unset | Exact string 1 disables this docs-only semantic shortcut |
mergeValidationConfig spreads worker defaults over run settings for top-level fields. Therefore the worker's codeChangesOnly wins when supplied. Only nested Crabbox/E2B options use run-specific precedence.
For a directly launched engine process:
export GILF_VALIDATION_CODE_CHANGES_ONLY=false
export GILF_CODEX_FOR_DOCS_ONLY=1The first allows validation on these diffs but does not override execution policy or executor readiness. The second disables only the docs-only semantic shortcut.
Native forwarding gap: neither flag is forwarded by cloudflare-native/src/container-env.js. Adding either to Worker vars alone does not change the container. The entrypoint supplies validationConfigFromEnv defaults and does not override the docs-only semantic setting.
Cost effect
When the shortcut applies with default-off optional workers and validation still skipped, it avoids sandbox execution and the semantic model call. Cloning, context/memory work, state and publication still occur, so this is not a zero-cost review. Generated-only diffs that are not also docs-only do not trigger this semantic shortcut.
The planner honors the semantic skip reason, but #runHypothesisReview is called before deterministic result selection even on this path. If an operator directly enables Prime or injects workers, those workers can still run. Do not promise zero model tokens after changing the default feature configuration.
Turn codeChangesOnly off only if your docs are executable (for example doctests) and the repo's validation scripts cover them.
Related
Source evidence
son-of-anton-review/src/codex-review-runner.js:711-720,833-848,1529-1544,1618-1649,2303-2315,2528-2548,2620-2657,2756-2769,3342-3353.son-of-anton-review/src/validation-config.js:11-31;src/config.js:11-14.son-of-anton-review/cloudflare-native/src/container-env.js:15-85;cloudflare-native/container/entrypoint.mjs:310-313,345-354.