# Xh Update Docs > 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 when this capability is needed. - Skill: `tomevault-io/xh-update-docs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/xh-update-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/xh-update-docs/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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 ` and `gh pr view ` 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 ~1..` **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 `/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](https://tomevault.io/claim/xh) — claim your Tome and manage your conversions.