What Is the Purpose of the `scripts/verify-docs-sync.py` Script in Diagram Design?

The scripts/verify-docs-sync.py script is a documentation-consistency validator that ensures every user-facing artifact in the Diagram Design skill—from SKILL.md front-matter to gallery pages and plugin manifests—remains perfectly synchronized with the canonical definitions of visual types and commands.

The scripts/verify-docs-sync.py file in the cathrynlavery/diagram-design repository serves as the central integrity checker for the Diagram Design skill's documentation ecosystem. According to the source code, this Python script aggregates ten distinct validation checks to detect drift between the skill's implementation and its public documentation. When executed, it walks the repository tree, reads markdown and JSON files, and exits with a non-zero status if any inconsistency is detected.

Core Architecture and Execution Flow

The validator orchestrates all checks through the main() function located at lines 37‑68 of the script. This entry point coordinates a series of focused validation routines, each targeting a specific class of documentation drift. The script distinguishes between two terminal states: "OK docs sync" indicates all validations passed, while "FAIL docs sync" precedes a detailed list of specific mismatches.

When validation fails, the script prints each error on a new line with a bullet prefix, identifying the exact file and nature of the inconsistency. This design allows the script to serve as a gatekeeper in continuous integration pipelines, preventing merges that would break documentation coherence.

The Ten Documentation Integrity Checks

The script implements granular validators for distinct documentation surfaces. Each check corresponds to a specific function in the source code.

SKILL.md Description Hooks

The check_description() function (lines 111‑130) verifies that the front-matter description in skills/diagram-design/SKILL.md contains a lexical hook for every visual type listed in the selection table. This ensures that the primary skill definition accurately reflects all supported diagram types.

Plugin Manifest Descriptions

The check_manifest_descriptions() function (lines 409‑435) validates that each plugin manifest—whether .claude-plugin, .codex-plugin, or .factory-plugin—repeats the SKILL.md description verbatim. This check preserves type hooks across all distribution channels.

Factory Install Surface

The check_factory_install_surface() function (lines 443‑485) ensures the README install block matches the native plugin manifest metadata. It also verifies that the architecture tree in the README correctly lists the native plugin path, maintaining consistency between installation documentation and actual file structure.

Gallery Reachability

The check_gallery() function (lines 136‑149) validates that every <data-type> tab in skills/diagram-design/assets/index.html points to an existing example HTML file. Conversely, it confirms that every shipped example is reachable from the gallery index, preventing orphaned demonstration files.

README Architecture Tree

The check_readme_tree() function (lines 161‑171) inspects the architecture tree code block under the "diagram-design/" section in README.md. It verifies that every file name referenced in the tree actually exists in the repository, catching stale or mistyped paths.

SKILL.md Reference Links

The check_skill_reference_links() function (lines 173‑187) validates that all relative links from SKILL.md into the references/ directory resolve to real files. This prevents broken documentation links when users navigate the skill reference.

Packaged Support References

The check_packaged_support_references() function (lines 199‑226) performs two critical validations. First, it ensures that every path a strict skill bundler could extract from SKILL.md is safe—containing no absolute paths, no parent directory references (..), and only allowed support directories. Second, it verifies that required runtime files (such as scripts/self_check.py, scripts/drawio_extract.py, and scripts/mermaid_extract.py) are properly exposed.

Routing Surfaces

The check_routing_surfaces() function (lines 228‑241) inspects command and prompt markdown files in commands/* and prompts/*. It validates that these files contain the correct reference links defined in the ROUTING_SURFACES map, ensuring navigation consistency across the skill's interface.

Type-Count Surfaces

The check_type_counts() function (lines 218‑334) prevents hard-coding of visual-type counts in files like commands/import-drawio.md. Instead of embedding literal numbers, these files must dynamically reference the count defined in SKILL.md, ensuring that type additions automatically propagate to dependent documentation.

High-Level Reference Invariants

The check_high_level_reference() function (lines 336‑366) validates the reproducibility checklist in references/type-high-level.md. It checks that the file maintains a sequential numbering scheme and correctly computes the effective_w value, preserving the integrity of advanced usage documentation.

Running the Validator Locally

Execute the script from the repository root to perform a full documentation audit:

cd /path/to/diagram-design
python3 scripts/verify-docs-sync.py

Successful validation produces output listing all passed checks:

OK docs sync: description hooks, gallery reachability, README tree, reference links,
packaged support files, routing surfaces, manifest descriptions, Factory install contract,
type-count routing, High-Level invariants

When the script detects drift, it exits with a non-zero status and outputs specific failure details:

FAIL docs sync
  - SKILL.md links to missing reference references/export.md
  - gallery cannot reach shipped example example-bar.html
  - README architecture tree names 'example-missing.html' but no such file exists

You can locate the offending file by matching the error message to the specific check function described above. For example, a "README architecture tree" error indicates check_readme_tree() found a non-existent file path in README.md.

Integrating with CI/CD

The script is designed for automated enforcement in GitHub Actions or similar pipelines. Add the following step to your workflow to block merges that introduce documentation inconsistencies:

- name: Verify documentation sync
  run: python3 scripts/verify-docs-sync.py

Because the script exits with a non-zero status on failure, the CI job will automatically fail, preventing the integration of changes that would desynchronize the skill's public documentation from its implementation.

Summary

• The scripts/verify-docs-sync.py script validates ten distinct documentation surfaces in the Diagram Design repository, from SKILL.md content to plugin manifests and gallery reachability.
• Key functions like check_description() (lines 111‑130), check_manifest_descriptions() (lines 409‑435), and check_gallery() (lines 136‑149) each enforce specific consistency rules.
• Execution via main() (lines 37‑68) produces either "OK docs sync" or "FAIL docs sync" output with detailed error reporting.
• CI Integration requires only a single command; the non-zero exit status automatically blocks inconsistent merges.
• Critical files under validation include skills/diagram-design/SKILL.md, README.md, plugin manifests (.claude-plugin, .factory-plugin), and runtime support scripts.

Frequently Asked Questions

What happens when verify-docs-sync.py finds a documentation mismatch?

The script prints "FAIL docs sync" followed by a bulleted list of specific errors, then exits with a non-zero status. Each error message identifies the exact file and nature of the drift, such as missing reference links or unreachable gallery examples, allowing precise remediation.

Which files does the script check?

The validator inspects skills/diagram-design/SKILL.md (the canonical source), README.md (architecture tree and install instructions), skills/diagram-design/assets/index.html (gallery reachability), plugin manifests (.claude-plugin, .codex-plugin, .factory-plugin), and all files in commands/*, prompts/*, and references/* directories.

How does the script validate plugin manifests?

The check_manifest_descriptions() function reads each plugin manifest file and compares its description field against the front-matter description in SKILL.md. The descriptions must match verbatim to ensure that visual type hooks remain consistent across Claude, Codex, and Factory distribution channels.

What is the ROUTING_SURFACES map mentioned in the code?

ROUTING_SURFACES is an internal mapping checked by check_routing_surfaces() (lines 228‑241) that defines the correct reference links for command and prompt files. The script validates that markdown files in commands/* and prompts/* contain links matching this canonical routing definition, ensuring navigation consistency throughout the skill interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}