Design Documentation Cross-Reference Graph

Generates visual graphs and reports showing relationships between design documents based on their frontmatter references and content links.

Overview

This skill analyzes design documentation to discover and visualize relationships between documents. It identifies orphaned docs, circular dependencies, cross-module references, and provides recommendations for improving documentation connectivity.

Quick Start

Full graph:

/design-link

Module-specific:

/design-link effect-type-registry

Find orphans:

/design-link --orphans

JSON output:

/design-link --format=json

Parameters

Optional

• module

  : Limit to specific module (default: all)

• format

  : Output format (mermaid, text, json) (default: mermaid)

• filter

  : Filter by relationship type (related, dependencies, content-links)

• orphans

  : Show only orphaned docs (default: false)

Workflow

High-level graph generation process:

1. Parse parameters to determine scope and output format
2. Load design.config.json to identify target modules
3. Find all design documents using Glob
4. Parse references from frontmatter (related, dependencies) and content links
5. Build graph with nodes (documents) and edges (references)
6. Analyze graph for orphans, circular dependencies, isolated clusters
7. Generate output in requested format (Mermaid, text, or JSON)
8. Provide recommendations for improving documentation connectivity

For detailed implementation steps, see supporting documentation below.

Supporting Documentation

When you need detailed information, load the appropriate supporting file:

For Detailed Workflow

See instructions.md for:

• Complete step-by-step graph generation workflow
• Reference extraction from frontmatter and content
• Graph building algorithm (nodes, edges, validation)
• Analysis algorithms (orphans, cycles, clusters)
• Output generation for each format
• Recommendation strategies
• Advanced features (metrics, subgraphs, impact analysis)

Load when: Generating graphs or need implementation details

For Graph Algorithms

See graph-algorithms.md for:

• Graph structure (nodes, edges)
• Orphan detection algorithm
• Circular dependency detection
• Connected components analysis
• Bidirectional and one-way detection
• Cross-module analysis
• Metrics calculation

Load when: Need algorithm details or implementing custom analysis

For Output Formats

See output-formats.md for:

• Mermaid diagram generation (syntax, styling, legends)
• Text report structure and sections
• JSON schema and format
• Format selection guidelines

Load when: Generating output or need format specifications

For Usage Examples

See examples.md for:

• Full graph for all modules
• Orphaned docs report
• Dependency graph only
• Module-specific graph
• Cross-module references
• Bidirectional vs one-way analysis
• Error scenarios (no docs, broken references)

Load when: User needs examples or clarification

Error Handling

No Design Docs Found

INFO: No design documents found in {module}

This is normal for new modules. Run /design-init to create your first
design doc.

Broken References

WARNING: Broken references detected in {doc}
- {broken-path-1}
- {broken-path-2}

Fix: Remove reference from frontmatter or create the missing document

Integration

Works well with:

• /design-review

  - Review docs flagged as orphaned

• /design-update

  - Add missing cross-references

• /design-validate

  - Ensure references are valid

• /design-search

  - Find related docs to add references

Success Criteria

A successful link analysis:

• ✅ All design docs discovered
• ✅ All references extracted (frontmatter + content)
• ✅ Graph built correctly
• ✅ Orphans identified
• ✅ Circular dependencies detected
• ✅ Clear visualization generated
• ✅ Actionable recommendations provided