xh-update-doc-links

xh-update-doc-links — Documentation Consistency Check

Pre-commit skill to ensure documentation index files, the MCP document registry, inter-doc links, and cross-references stay consistent after editing feature-area docs.

Step 1: Discover Documentation Files

Build a complete inventory of documentation files on disk.

1. Use Glob to find all files matching docs/*.md (feature-area docs).
2. Use Glob to find all files matching docs/upgrade-notes/*.md.
3. Exclude docs/planning/ from the doc inventory — those are meta/planning files, not feature-area documentation.
4. Run git diff --name-only and git status --porcelain to identify which docs were recently changed or added.
5. Build a master list of all documentation files, noting which are new or recently modified.

Step 2: Read Index Files

Read the two index files and parse their current entries.

1. Read docs/README.md — focus on the Feature Documentation section (the tables under "Core Framework", "Core Features", "Infrastructure & Operations", "Grails Platform", "Development & Builds") and the Quick Reference by Task table.

   • Parse each table row to extract the linked filename and description.

2. Read docs/planning/docs-roadmap.md — parse all priority tables and the Grails Platform table.

   • Extract each document name, description, and status value.
   • Note which entries are Planned, Draft, or Done.

Step 3: Reconcile Indexes

Compare documentation on disk against both index files.

docs/README.md Reconciliation

For each feature-area doc on disk:

• Check if it has an entry in the appropriate docs/README.md table (Core Framework, Core Features, Infrastructure & Operations, Grails Platform, or Development & Builds).
• Missing entries: Add a new table row in the correct section using this format:

  | [`filename.md`](./filename.md) | One-sentence description | Key, Topics, Here |
  

• Stale entries: If an entry links to a doc that no longer exists, remove it.
• Quick Reference: Check if a new doc should have a "If you need to..." entry in the Quick Reference by Task table. Add one if the doc covers a common task.
• AGENTS.md directive: Verify that AGENTS.md still contains the directive pointing to docs/README.md (the "Documentation" section). Do not re-add documentation tables to AGENTS.md.