| name | xh-update-docs |
| description | Update hoist-react documentation after adding new components or features. Use when a developer has made changes to hoist-react and wants to update README files, AGENTS.md, and the documentation roadmap (docs/planning/docs-roadmap.md) to reflect those changes. Invoke with a commit hash or PR number. Also use when you detect that recent commits or PRs have added new components, models, or services that are not yet reflected in the documentation. Use whenever asked to "document recent changes", "update the docs for this PR", or "write a README for this package". This skill writes and updates documentation content — for syncing indexes, links, and the doc registry without writing new content, see `xh-update-doc-links`. |
| tools | Read, Glob, Grep, Bash, Edit, Write |
xh-update-docs — Documentation Update Skill
Update hoist-react documentation to reflect recent code changes. This skill analyzes
commits or PRs, identifies documentation-worthy changes, and proposes targeted updates
to package READMEs, AGENTS.md, and the documentation roadmap.
This skill writes and updates documentation content. For syncing indexes, inter-doc links,
and the doc registry without writing new content, see xh-update-doc-links.
Step 1: Resolve Input
Accept $ARGUMENTS as a commit hash or PR number.
If arguments are provided:
- If it looks like a PR number (digits only, typically 1-5 digits):
- Preferred: Use
gh pr diff <number> and gh pr view <number> to analyze
- If
gh CLI is not available: Use the GitHub MCP server tools instead — call
pull_request_read with method get_diff for the unified diff and method details
for PR metadata. The MCP server is configured in .mcp.json at the repo root.
- If neither
gh nor the GitHub MCP server is available: Ask the user to provide
the commit hash instead, or to check out the PR branch locally.
- Otherwise treat it as a commit hash and use
git diff <hash>~1..<hash>
If no arguments are provided:
- Run
git log --oneline -6 to fetch the last 6 commits
- Present them to the user via
AskUserQuestion as selectable options, where each option
label is the short hash + commit message
- The user picks the commit(s) that contain the changes to document
Step 2: Analyze Changes
Analyze the diff to identify documentation-worthy changes:
-
Identify new and modified files:
- New files added (new components, models, services)
- Modified files (changed behavior, new props/config, new methods)
-
Determine affected packages:
- Map changed files to packages:
/cmp/, /core/, /data/, /svc/, /desktop/,
/mobile/, /admin/, /format/, /utils/, etc.
-
Read source files:
- Don't just rely on the diff — read the actual source files to understand what was
added or changed, including class hierarchies and exported APIs
-
Cross-reference CHANGELOG.md:
- Check
CHANGELOG.md for entries related to the commit/PR
- The changelog uses categorized sections under version headers:
💥 Breaking Changes, 🎁 New Features, ⚙️ Technical, 🐞 Bug Fixes
- Look for entries in the current SNAPSHOT version that describe the change
- These provide curated descriptions and are a strong signal of documentation-worthy changes
Step 3: Inventory Existing Documentation
Check current documentation state for each affected package:
-
Package READMEs — Read the relevant README(s) to see what's already documented.
Use Glob to check for <package>/README.md files.
-
Documentation Index — Check for existing entries in the docs/README.md Package
Documentation tables. Read docs/README.md and look for the affected package paths.
-
Documentation Roadmap — Check docs/planning/docs-roadmap.md for status of affected packages.
-
Document Registry — Check docs/doc-registry.json for existing entries matching the
affected packages. Each entry's id is the file path (e.g. cmp/grid/README.md).
Step 4: Propose Updates
Generate a categorized list of proposed documentation changes. For each change, explain
what would be updated and why.
Categories:
README Updates
Edits to existing package READMEs. Examples:
- New section for a newly added component or model
- Updated configuration table with new properties
- New usage pattern or code example
- Updated architecture diagram
- New entry in Common Pitfalls
New READMEs
If a new sub-package was added that lacks a README, propose creating one following the
7-section structure defined in references/doc-conventions.md.
Documentation Index Updates
New or updated entries in the docs/README.md Package Documentation tables. Each entry needs:
- Linked package path (relative from
docs/, e.g., ../package/README.md)
- One-sentence description
- Comma-separated list of key topics
Registry Updates
New or updated entries in docs/doc-registry.json:
- New entries for newly documented packages/concepts (with
id = file path, title,
mcpCategory, viewerCategory, description, keywords)
- Updated keywords or descriptions for existing entries affected by the changes
Roadmap Updates
Status changes in docs/planning/docs-roadmap.md:
- New package entries added to the appropriate priority tier
- Status changes (e.g.,
Planned → Done with link)
Progress notes in docs/planning/docs-roadmap-log.md:
- When meaningful changes occur (new READMEs created, roadmap status promotions — not minor
edits or cosmetic fixes), append a new dated entry following the existing chronological format
Step 5: Confirm with User
Present the full list of proposed changes in a clear summary. Ask the user to confirm
before applying any changes. Group by category and include enough context for the user
to evaluate each proposed change.
Step 6: Apply Changes
After user confirmation, apply the approved documentation updates using Edit and Write tools.
Follow conventions from references/doc-conventions.md:
- Use the 7-section README structure for new READMEs
- Use element factory style in code examples (not JSX)
- Use
config (not props) for model constructor args
- Fold defaults into description column (no separate Default column)
- Use ✅/❌ markers for correct/incorrect code patterns
- Use
**Avoid:** prefix for inline warnings
After applying changes, present a summary of what was updated.
