xh-update-docs

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:

1. Identify new and modified files:

   • New files added (new components, models, services)
   • Modified files (changed behavior, new props/config, new methods)

2. Determine affected packages:

   • Map changed files to packages: /cmp/, /core/, /data/, /svc/, /desktop/, /mobile/, /admin/, /format/, /utils/, etc.

3. 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

4. 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:

1. Package READMEs — Read the relevant README(s) to see what's already documented. Use Glob to check for <package>/README.md files.

2. 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.

3. Documentation Roadmap — Check docs/planning/docs-roadmap.md for status of affected packages.

4. 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.