Xh Update Docs

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.

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

• 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

When new docs are added, also update docs/doc-registry.json with a new entry containing id (= file path), title, mcpCategory, viewerCategory, description, and keywords.

After applying changes, present a summary of what was updated.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.