[docs] Self-healing documentation fixes from issue analysis - 2026-06-09#37980
[docs] Self-healing documentation fixes from issue analysis - 2026-06-09#37980github-actions[bot] wants to merge 1 commit into
Conversation
Issue #36275 asked the frontmatter reference page to cover three top-level fields (`check-for-updates`, `disable-model-invocation`, `run-install-scripts`) so the in-schema anchor links resolve. Two were added but `disable-model-invocation` was left undocumented in `docs/src/content/docs/reference/frontmatter.md` — it only appeared in the auto-generated `frontmatter-full.md` dump. This adds a curated section so users browsing the reference can see what the field does. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
🧪 Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. PR #37980 only modifies docs/src/content/docs/reference/frontmatter.md (documentation). Test Quality Sentinel skipped. |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #37980 does not have the 'implementation' label (has_implementation_label=false) and has 0 new lines of code in business logic directories (well under the 100-line threshold). The PR consists of documentation/skill-script changes, which do not warrant an Architecture Decision Record. |
|
✅ PR Code Quality Reviewer completed the code quality review. |
There was a problem hiding this comment.
Pull request overview
This PR updates the curated frontmatter reference to cover the previously undocumented disable-model-invocation field, closing a documentation gap identified in issue #36275 and ensuring users can find this option in the non-auto-generated reference page.
Changes:
- Adds a new
### disable-model-invocationsection to the curated frontmatter reference. - Provides a YAML example and short guidance, including a migration note about the
infer→disable-model-invocationcodemod.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/frontmatter.md | Adds a curated reference entry for disable-model-invocation. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 2
|
|
||
| ### `disable-model-invocation` | ||
|
|
||
| Controls whether the custom agent file produced by the workflow can be auto-invoked by a host model. When set to `true`, downstream tooling treats the agent as documentation-only and will not call into it. |
| disable-model-invocation: true | ||
| ``` | ||
|
|
||
| Use this on skill or sub-agent files that should be loaded as reference material rather than executed (for example, `.github/aw/*.md` skill files). The `gh aw fix --write` codemod `infer-to-disable-model-invocation` migrates the deprecated `infer:` field to this one, inverting the boolean. |
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — three observations on the new disable-model-invocation section, none merge-blocking.
📋 Key Themes & Highlights
Key Themes
- ADR-33808 constraint: The last sentence in the added paragraph names the deprecated
infer:field. ADR-33808 §Schema/Parser rule 4 explicitly says the field description MUST NOT back-referenceinfer. The ADR is still in Draft, but the intent is to keep this page free of the deprecated name — worth removing or moving that sentence. - Missing default value: Unlike
check-for-updatesdirectly above (which says "Whentrue(default)"), the new section doesn't state what the field defaults to. Adding "The default isfalse(model invocation is enabled)" closes that gap. - Prose drift from
frontmatter-full.md: The auto-generated page frames the field as preventing "additional model calls" (runtime behavior); the curated page frames it as "downstream tooling treats the agent as documentation-only" (metadata marker). A single canonical sentence used on both pages would avoid reader confusion.
Positive Highlights
- ✅ Correctly placed between
check-for-updatesandFeature Flags, matching the ordering infrontmatter-full.md - ✅ Includes a minimal
yaml wrapcode example consistent with all sibling fields - ✅ Use-case note (
.github/aw/*.mdskill files) adds real value for readers discovering the field for the first time
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 209.5 AIC · ⌖ 34.5 AIC
|
|
||
| ### `disable-model-invocation` | ||
|
|
||
| Controls whether the custom agent file produced by the workflow can be auto-invoked by a host model. When set to `true`, downstream tooling treats the agent as documentation-only and will not call into it. |
There was a problem hiding this comment.
[/grill-with-docs] Missing default value — the description does not state what happens when disable-model-invocation is omitted.
Sibling fields like check-for-updates explicitly say "When true (default)" or "The default is false". Without a stated default, users cannot know whether model invocation is on or off when the field is absent.
💡 Suggested addition
Append to the first paragraph:
Controls whether the custom agent file produced by the workflow can be auto-invoked by a host model. When set to `true`, downstream tooling treats the agent as documentation-only and will not call into it. The default is `false` (model invocation is enabled).
This matches the pattern established by check-for-updates just above.
| disable-model-invocation: true | ||
| ``` | ||
|
|
||
| Use this on skill or sub-agent files that should be loaded as reference material rather than executed (for example, `.github/aw/*.md` skill files). The `gh aw fix --write` codemod `infer-to-disable-model-invocation` migrates the deprecated `infer:` field to this one, inverting the boolean. |
There was a problem hiding this comment.
[/grill-with-docs] Back-reference to infer may conflict with ADR-33808 — consider removing it from the field description.
ADR-33808 §"Schema and Parser" rule 4 states: "The disable-model-invocation field description MUST NOT contain a back-reference to infer." The sentence "The gh aw fix --write codemod infer-to-disable-model-invocation migrates the deprecated infer: field to this one, inverting the boolean" directly names the deprecated field. The ADR’s rationale is to avoid burdening new readers with a concept they should never need to know.
💡 Suggested revision
Remove the codemod sentence from this paragraph entirely. Users who need to migrate from the deprecated infer field can run gh aw fix --write and the codemod handles the conversion automatically — they don’t need the curated reference page to explain it.
If migration guidance is still desired, a dedicated "Migration from infer" section elsewhere (e.g., a migration guide or the codemod’s own docs page) would keep this reference page clean.
|
|
||
| ### `disable-model-invocation` | ||
|
|
||
| Controls whether the custom agent file produced by the workflow can be auto-invoked by a host model. When set to `true`, downstream tooling treats the agent as documentation-only and will not call into it. |
There was a problem hiding this comment.
[/grill-with-docs] Description drifts from frontmatter-full.md — the two pages describe the same field differently.
frontmatter-full.md says the field means "the agent will not make additional model calls", while this curated section says "downstream tooling treats the agent as documentation-only." These framings are semantically distinct (runtime behavior vs. metadata marker) and could leave readers unsure which is accurate.
💡 Suggested alignment
Pick one canonical framing and use it consistently. The frontmatter-full.md version is auto-generated from the schema description; aligning the curated prose to match (or updating the schema description to match the curated prose) would make both pages consistent:
Controls whether the custom agent file produced by the workflow can be auto-invoked by a host model. When set to
true, the agent will not make additional model calls and downstream tooling treats it as documentation-only.
There was a problem hiding this comment.
REQUEST_CHANGES — 1 blocking + 1 non-blocking issue
The new disable-model-invocation section is otherwise well-structured and the content is accurate, but it must not merge as-is.
Blocking issue
ADR-33808 normative violation (line 478): the last sentence of the added section references the deprecated infer: field and the infer-to-disable-model-invocation codemod. ADR-33808, Part 2, item 4 explicitly requires: "The disable-model-invocation field description MUST NOT contain a back-reference to infer." Remove that sentence.
Non-blocking issue
Missing default (line 472): the description doesn't state what happens when the field is omitted (model invocation is enabled by default). Every peer section (check-for-updates, run-install-scripts) states the default. Worth fixing in the same pass.
🔎 Code quality review by PR Code Quality Reviewer · 11.9 AIC · ⌖ 12.7 AIC
| disable-model-invocation: true | ||
| ``` | ||
|
|
||
| Use this on skill or sub-agent files that should be loaded as reference material rather than executed (for example, `.github/aw/*.md` skill files). The `gh aw fix --write` codemod `infer-to-disable-model-invocation` migrates the deprecated `infer:` field to this one, inverting the boolean. |
There was a problem hiding this comment.
ADR-33808 normative violation: this sentence back-references the deprecated infer: field, which the project ADR explicitly forbids in this description.
💡 Details and fix
ADR-33808 Part 2 "Schema and Parser" item 4 states:
The
disable-model-invocationfield description MUST NOT contain a back-reference toinfer.
The sentence to remove:
The
gh aw fix --writecodemodinfer-to-disable-model-invocationmigrates the deprecatedinfer:field to this one, inverting the boolean.
Drop it entirely. Migration guidance belongs in release notes, not in the field reference — and the ADR prohibits it here. The preceding sentence already gives users sufficient context for when to use this field.
|
|
||
| ### `disable-model-invocation` | ||
|
|
||
| Controls whether the custom agent file produced by the workflow can be auto-invoked by a host model. When set to `true`, downstream tooling treats the agent as documentation-only and will not call into it. |
There was a problem hiding this comment.
Missing default: the description doesn't say what the default is when the field is omitted, leaving users unsure whether model invocation is enabled by default.
💡 Suggested fix
The adjacent check-for-updates section sets the pattern: "When true (default)...". Apply the same convention here. Since omitting the field means model invocation is enabled, add a sentence like:
When
true, downstream tooling treats the agent as documentation-only and will not call into it. Omitting this field (or setting it tofalse) leaves model invocation enabled.
Without this, users have no way to know the field's default from the reference page alone.
Self-Healing Documentation Fixes
This PR was automatically created by the Daily Documentation Healer workflow.
Gaps Fixed
disable-model-invocationwas one of three top-level frontmatter fields the issue asked to document so the in-schema anchor link resolves. The other two (check-for-updates,run-install-scripts) were added when the issue was closed, butdisable-model-invocationwas left undocumented in the curated reference page — it only appears in the auto-generatedfrontmatter-full.md. This PR adds a short curated section indocs/src/content/docs/reference/frontmatter.md.Root Cause
Issue #36275 was closed as COMPLETED but only partially fixed: two of the three fields were documented while
disable-model-invocationwas missed. DDUw did not re-detect the residual gap because its current sweep does not cross-check that every field with an in-schema anchor link resolves to a heading indocs/src/content/docs/reference/frontmatter.md. The auto-generatedfrontmatter-full.mdcovers the field, so a naive grep acrossdocs/for the field name succeeds and the gap is invisible.DDUw Improvement Suggestions
DDUw Improvement Suggestions
Add targeted scan steps to
.github/workflows/daily-doc-updater.mdunder section 2 (Analyze Changes → Removed Features in Docs):Schema-anchor resolver check — for every
descriptioninpkg/parser/schemas/main_workflow_schema.jsonthat links toreference/frontmatter/#<anchor>, verify a matching heading exists indocs/src/content/docs/reference/frontmatter.md. Excludefrontmatter-full.mdfrom the check (auto-generated; always passes).Partial-fix detection for closed issues — when DDUw scans recently closed
documentationissues, treat each bullet or acceptance-criterion line as a separate verifiable claim and grep each one. Issue [deep-report] [quick-win] Document 3 undocumented top-level frontmatter fields + fix broken in-schema anchors #36275 missed exactly one of three bullets because the issue was treated as a single unit.Both checks are mechanical, fast, and would have caught this drift the day after #36275 was closed.
Related Issues