Skip to content

[docs] Self-healing documentation fixes from issue analysis - 2026-06-09 #37980

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
github-actions wants to merge 1 commit into from
+10 −0
Closed

[docs] Self-healing documentation fixes from issue analysis - 2026-06-09 #37980

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/src/content/docs/reference/frontmatter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -467,6 +467,16 @@ check-for-updates: true

When `true` (default), the activation job verifies the compiled version is not blocked and meets the minimum supported version. Set to `false` to disable this check (not allowed in strict mode).

### `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.

@github-actions github-actions Bot Jun 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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.

@github-actions github-actions Bot Jun 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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.

@github-actions github-actions Bot Jun 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 to false) leaves model invocation enabled.

Without this, users have no way to know the field's default from the reference page alone.


```yaml wrap
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.

@github-actions github-actions Bot Jun 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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.

@github-actions github-actions Bot Jun 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-invocation field description MUST NOT contain a back-reference to infer.

The sentence to remove:

The gh aw fix --write codemod infer-to-disable-model-invocation migrates the deprecated infer: 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.


### Feature Flags (`features:`)

Enable experimental or optional compiler and runtime behaviors as key-value pairs. See [Feature Flags](/gh-aw/reference/feature-flags/) for complete documentation.
Expand Down
Loading