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

> Understand the purpose of the scripts/verify-docs-sync.py script in Diagram Design. This validator ensures user-facing documentation stays perfectly synchronized with canonical definitions.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-22

---

**The [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py), [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py), and [`scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md). Instead of embedding literal numbers, these files must dynamically reference the count defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```

Successful validation produces output listing all passed checks:

```text
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:

```text
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```yaml
- 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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) script** validates ten distinct documentation surfaces in the Diagram Design repository, from [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md), plugin manifests (`.claude-plugin`, `.factory-plugin`), and runtime support scripts.

## Frequently Asked Questions

### What happens when [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) (the canonical source), [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) (architecture tree and install instructions), [`skills/diagram-design/assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.