Build: Add docs-review skill#34451
Merged
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughAdds a new docs-review AI skill and four reference guides that define scope, intent→mode routing, doc-type classification, ordered diagnosis across quality dimensions, intervention thresholds, mode-specific actions, Storybook editorial rules, antipatterns, and validation/handoff constraints for Changes
Sequence Diagram(s)sequenceDiagram
participant User as User
participant Skill as Docs-Review Skill
participant Refs as References (Principles/Strategy/Antipatterns/Style)
participant Classifier as Doc-Type Classifier
participant Editor as Editor/Agent Edits
participant Validator as Validator (yarn fmt:write / yarn docs:check)
participant PR as PR Skill
User->>Skill: Submit review request + files
Skill->>Refs: Load ordered references
Skill->>Classifier: Classify primary doc type (& optional secondary)
Skill->>Skill: Map intent → mode (maintenance/improve/rewrite/author/strategy)
Skill->>Refs: Run diagnosis across quality dimensions (use antipatterns as needed)
Skill->>Editor: Generate edits or planning artifact (strategy)
Editor-->>Skill: Return edits or plan
alt edit mode
Skill->>Validator: Run formatting & docs checks
Validator-->>Skill: Return validation results
else strategy mode
Note over Skill,Editor: No formatting/validation
end
Skill->>PR: Provide handoff details (no auto-PR creation)
PR-->>User: Handoff/PR summary (if requested)
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/skills/docs-review/SKILL.md:
- Line 90: The sentence "For secondary sections, evaluate dimensions 3
(Information Shape) and 5 (Task Usability) against the secondary section's own
doc type, not the page's primary type. All other dimensions apply page-wide."
conflicts with references/docs-strategy.md; update the line in SKILL.md so that
the rule clearly states secondary sections are evaluated by their own doc-type
criteria (i.e., apply the section's doc-type criteria to the secondary section
for all relevant dimensions) and remove the special-case limiting to dimensions
3 and 5; ensure the wording references the same "secondary sections" rule as in
references/docs-strategy.md to avoid inconsistent diagnosis behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 6653d984-8124-4fd7-8d09-075022b7ee74
📒 Files selected for processing (4)
.agents/skills/docs-review/SKILL.md.agents/skills/docs-review/references/docs-antipatterns.md.agents/skills/docs-review/references/docs-principles.md.agents/skills/docs-review/references/docs-strategy.md
✅ Files skipped from review due to trivial changes (2)
- .agents/skills/docs-review/references/docs-principles.md
- .agents/skills/docs-review/references/docs-antipatterns.md
| 6. Example quality | ||
| 7. Economy | ||
|
|
||
| For secondary sections, evaluate dimensions 3 (Information Shape) and 5 (Task Usability) against the secondary section's own doc type, not the page's primary type. All other dimensions apply page-wide. |
Contributor
There was a problem hiding this comment.
Secondary-section evaluation rule conflicts with docs-strategy.md.
This line narrows secondary-section evaluation to dimensions 3 and 5, but references/docs-strategy.md states secondary sections should be evaluated by their own doc-type criteria. Please align this to avoid inconsistent diagnosis behavior.
Suggested fix
-For secondary sections, evaluate dimensions 3 (Information Shape) and 5 (Task Usability) against the secondary section's own doc type, not the page's primary type. All other dimensions apply page-wide.
+For secondary sections, evaluate them against their own doc type's criteria (as defined in `references/docs-strategy.md`), not the page's primary type. Apply page-wide dimensions where appropriate.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| For secondary sections, evaluate dimensions 3 (Information Shape) and 5 (Task Usability) against the secondary section's own doc type, not the page's primary type. All other dimensions apply page-wide. | |
| For secondary sections, evaluate them against their own doc type's criteria (as defined in `references/docs-strategy.md`), not the page's primary type. Apply page-wide dimensions where appropriate. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/skills/docs-review/SKILL.md at line 90, The sentence "For secondary
sections, evaluate dimensions 3 (Information Shape) and 5 (Task Usability)
against the secondary section's own doc type, not the page's primary type. All
other dimensions apply page-wide." conflicts with references/docs-strategy.md;
update the line in SKILL.md so that the rule clearly states secondary sections
are evaluated by their own doc-type criteria (i.e., apply the section's doc-type
criteria to the secondary section for all relevant dimensions) and remove the
special-case limiting to dimensions 3 and 5; ensure the wording references the
same "secondary sections" rule as in references/docs-strategy.md to avoid
inconsistent diagnosis behavior.
Pages still have one primary doc type, but well-structured secondary sections (e.g., a reference table at the end of a task page) are now recognized and evaluated by their own type's criteria instead of being flagged as an antipattern or triggering a split recommendation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
.agents/skills/docs-review/SKILL.md (1)
90-90:⚠️ Potential issue | 🟠 MajorSecondary-section evaluation rule conflicts with
docs-strategy.md.This line limits secondary-section evaluation to dimensions 3 and 5, but
references/docs-strategy.mdline 26 states that "each secondary section is evaluated by its own type's criteria" without restricting which dimensions apply. This creates inconsistent diagnosis behavior between the two reference documents.The strategy document's broader guidance (evaluate by the section's own doc-type criteria) is more aligned with the well-structured secondary sections described in lines 57-61 of
docs-strategy.md.Suggested fix
-For secondary sections, evaluate dimensions 3 (Information Shape) and 5 (Task Usability) against the secondary section's own doc type, not the page's primary type. All other dimensions apply page-wide. +For secondary sections, evaluate them against their own doc type's criteria (as defined in `references/docs-strategy.md`). Apply page-wide dimensions where appropriate.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/docs-review/SKILL.md at line 90, The rule in SKILL.md restricting secondary-section evaluation to only dimensions 3 (Information Shape) and 5 (Task Usability) conflicts with references/docs-strategy.md; update the SKILL.md wording so that each secondary section is evaluated using its own doc-type criteria for all relevant dimensions (not just 3 and 5), ensuring consistency with the guidance in docs-strategy.md and the "well-structured secondary sections" rules referenced there.
🧹 Nitpick comments (1)
.agents/skills/docs-review/SKILL.md (1)
69-69: Clarify "lookup" phrasing.The word "lookup" is unclear here. Consider "look up options" or "reference for options" for better readability.
📝 Suggested refinement
-- `reference` — lookup for options, API, or config +- `reference` — look up options, API, or config🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/docs-review/SKILL.md at line 69, Change the phrasing for the `reference` entry to avoid the unclear single-word "lookup"; update the text to something like "`reference` — reference for options, API, or config" or "`reference` — look up options, API, or config" so it reads clearly; edit the SKILL.md line containing "`reference` — lookup for options, API, or config" to use one of these clearer alternatives.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/skills/docs-review/references/storybook-style.md:
- Line 85: Update the wording in the line that reads "External: full URLs,
always wrapped in markdown link syntax (no bare URLs in prose). `[auto]`" to
capitalize the formatting language as "Markdown" (i.e., change "markdown link
syntax" to "Markdown link syntax") so the proper noun is used consistently
across the document.
---
Duplicate comments:
In @.agents/skills/docs-review/SKILL.md:
- Line 90: The rule in SKILL.md restricting secondary-section evaluation to only
dimensions 3 (Information Shape) and 5 (Task Usability) conflicts with
references/docs-strategy.md; update the SKILL.md wording so that each secondary
section is evaluated using its own doc-type criteria for all relevant dimensions
(not just 3 and 5), ensuring consistency with the guidance in docs-strategy.md
and the "well-structured secondary sections" rules referenced there.
---
Nitpick comments:
In @.agents/skills/docs-review/SKILL.md:
- Line 69: Change the phrasing for the `reference` entry to avoid the unclear
single-word "lookup"; update the text to something like "`reference` — reference
for options, API, or config" or "`reference` — look up options, API, or config"
so it reads clearly; edit the SKILL.md line containing "`reference` — lookup for
options, API, or config" to use one of these clearer alternatives.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f84e5060-fedc-40e2-9cc4-363dac85229f
📒 Files selected for processing (5)
.agents/skills/docs-review/SKILL.md.agents/skills/docs-review/references/docs-antipatterns.md.agents/skills/docs-review/references/docs-principles.md.agents/skills/docs-review/references/docs-strategy.md.agents/skills/docs-review/references/storybook-style.md
✅ Files skipped from review due to trivial changes (1)
- .agents/skills/docs-review/references/docs-principles.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .agents/skills/docs-review/references/docs-antipatterns.md
| ## Links | ||
|
|
||
| - Internal: relative paths to `.mdx` files, e.g. `[text](../path/to/file.mdx)`. `[auto]` | ||
| - External: full URLs, always wrapped in markdown link syntax (no bare URLs in prose). `[auto]` |
Contributor
There was a problem hiding this comment.
Capitalize "Markdown" as a proper noun.
The word "markdown" should be capitalized as "Markdown" when referring to the formatting language.
📝 Proposed fix
-External: full URLs, always wrapped in markdown link syntax (no bare URLs in prose). `[auto]`
+External: full URLs, always wrapped in Markdown link syntax (no bare URLs in prose). `[auto]`🧰 Tools
🪛 LanguageTool
[uncategorized] ~85-~85: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ... External: full URLs, always wrapped in markdown link syntax (no bare URLs in prose). `[...
(MARKDOWN_NNP)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/skills/docs-review/references/storybook-style.md at line 85, Update
the wording in the line that reads "External: full URLs, always wrapped in
markdown link syntax (no bare URLs in prose). `[auto]`" to capitalize the
formatting language as "Markdown" (i.e., change "markdown link syntax" to
"Markdown link syntax") so the proper noun is used consistently across the
document.
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.
What I did
See title
Checklist for Contributors
Testing
The changes in this PR are covered in the following automated tests:
Manual testing
Documentation
MIGRATION.MD
Checklist for Maintainers
When this PR is ready for testing, make sure to add
ci:normal,ci:mergedorci:dailyGH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found incode/lib/cli-storybook/src/sandbox-templates.tsMake sure this PR contains one of the labels below:
Available labels
bug: Internal changes that fixes incorrect behavior.maintenance: User-facing maintenance tasks.dependencies: Upgrading (sometimes downgrading) dependencies.build: Internal-facing build tooling & test updates. Will not show up in release changelog.cleanup: Minor cleanup style change. Will not show up in release changelog.documentation: Documentation only changes. Will not show up in release changelog.feature request: Introducing a new feature.BREAKING CHANGE: Changes that break compatibility in some way with current major version.other: Changes that don't fit in the above categories.Summary by CodeRabbit