Docs Graph

How It Works

The graph is automatically updated via Claude Code hooks whenever files in plans/ are created or modified. This skill provides on-demand viewing and querying.

Automatic Updates

PostToolUse hook triggers on Write/Edit to plans/:

1. Hook detects file path contains plans/
2. Runs python3 scripts/graph.py --check-path <path>
3. Graph files updated before next Claude action

Graph Files

plans/
├── docs-graph.json    # Machine-readable graph data
└── docs-graph.md      # Mermaid visualization

Workflow

Phase 1: Load Graph

1. Check if plans/docs-graph.json exists
2. If not, run python3 scripts/graph.py to generate
3. Read graph data

Phase 2: Display or Query

Summary mode (default):

• Show node count by type
• Show edge count
• Display mermaid diagram from docs-graph.md
• List any errors

Query mode (with argument):

• Filter nodes matching query
• Show incoming links (what references this)
• Show outgoing links (what this references)

Regenerate mode (--regenerate):

• Force full rescan of plans/
• Update docs-graph.json and docs-graph.md
• Show diff if changes detected

Check mode (--check):

• Verify all wikilinks resolve to existing nodes
• Report broken links
• Suggest fixes

Phase 3: Output

Display results with:

• Mermaid diagram (if summary)
• Table of matching nodes (if query)
• Broken link report (if check)

Wikilink Convention

Documents use [[wikilinks]] to reference each other:

# UC-AUTH-001: Login

> **Feature**: [[feature-auth]]
> **Related**: [[uc-auth-002]], [[uc-auth-003]]
> **Spec**: [[spec-auth-001]]

Link ID format:

• Use cases: [[uc-auth-001]] (lowercase, no slug)
• Features: [[feature-auth]]
• Specs: [[spec-auth-001]]
• Change requests: [[cr-001]]

Node Types

Example Output

Summary

Documentation Graph Summary
===========================
Nodes: 12 | Edges: 18

By Type:
  use-case: 5
  feature: 2
  spec: 4
  brd: 1

View full graph: plans/docs-graph.md

Query: /docs-graph auth

Nodes matching "auth": 4

uc-auth-001 (use-case) - Login
  ← feature-auth, spec-auth-001
  → feature-auth

uc-auth-002 (use-case) - Signup
  ← feature-auth
  → uc-auth-001, feature-auth

feature-auth (feature) - Authentication
  ← uc-auth-001, uc-auth-002, uc-auth-003
  → (none)

spec-auth-001 (spec) - Login Spec
  ← (none)
  → uc-auth-001

Check: /docs-graph --check

Link Check Results
==================
✓ 16 valid links
✗ 2 broken links

Broken:
  plans/brd/use-cases/auth/UC-AUTH-001-login.md:5
    [[uc-auth-004]] - node not found

  plans/features/auth/specs/UC-AUTH-001/README.md:12
    [[feature-billing]] - node not found

Suggestions:
  - uc-auth-004: Did you mean uc-auth-003?
  - feature-billing: Create plans/features/billing/README.md

Tools Used

Integration

Troubleshooting

Graph not updating:

• Check hook is in .claude/settings.local.json
• Verify jq is installed
• Run /docs-graph --regenerate to force update

Broken links:

• Run /docs-graph --check to find issues
• Update wikilinks to match node IDs
• Node IDs are lowercase, no slug (e.g., uc-auth-001 not UC-AUTH-001-login)