Add an outcome statement linter - #674
Draft
ptgott wants to merge 1 commit into
Draft
Conversation
|
Amplify deployment status
|
ptgott
force-pushed
the
paul.gottschling/2026-05-19-outcome
branch
from
May 26, 2026 12:58
68c9ee3 to
e3256d4
Compare
ptgott
force-pushed
the
paul.gottschling/2026-05-19-outcome
branch
from
May 26, 2026 17:06
e3256d4 to
53cad20
Compare
ptgott
force-pushed
the
paul.gottschling/2026-05-19-outcome
branch
from
May 26, 2026 17:25
53cad20 to
bd3d7e5
Compare
ptgott
force-pushed
the
paul.gottschling/2026-05-19-outcome
branch
from
June 23, 2026 16:01
bd3d7e5 to
c3fdf86
Compare
Add outcome statement helps human and AI agent readers determine the scope of a docs page within a single paragraph so they can make a decision as to whether to continue reading. While there is currently a check for opening paragraphs in docs pages, the outcome statement check goes a step further and requires a specific sentence structure depending on the kind of guide, which it obtains from the `page_type` frontmatter field. This helps ensure that docs authors include the most appropriate level of detail in each page's outcome statement. For example, while an LLM can determine the scope of a reference page based on the tables, lists, and so on, this linter enforces the presence of an explicit description of the kinds of items a page lists: "This page lists the...". To implement the outcome statement linter, this change adds a check to lint-page-structure.
ptgott
force-pushed
the
paul.gottschling/2026-05-19-outcome
branch
from
July 23, 2026 13:32
c3fdf86 to
2604d00
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add outcome statement helps human and AI agent readers determine the scope of a docs page within a single paragraph so they can make a decision as to whether to continue reading.
While there is currently a check for opening paragraphs in docs pages, the outcome statement check goes a step further and requires a specific sentence structure depending on the kind of guide, which it obtains from the
page_typefrontmatter field. This helps ensure that docs authors include the most appropriate level of detail in each page's outcome statement.For example, while an LLM can determine the scope of a reference page based on the tables, lists, and so on, this linter enforces the presence of an explicit description of the kinds of items a page lists: "This page lists the...".
To implement the outcome statement linter, this change adds a check to lint-page-structure.