gh-witt3rd-claude-plugins-plugins-azkg/commands/graph-stats.md

description

description
Display comprehensive statistics about the knowledge graph

Graph Stats

Display comprehensive statistics about the knowledge graph.

0. Locate AZKG Repository

Check for AZKG_REPO_PATH environment variable:

• Use bash conditional: if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi
• If AZKG_REPO_PATH is set: Use that path as the repository root
• If AZKG_REPO_PATH is not set: Use current working directory (pwd)
• Store result as REPO_PATH for all subsequent file operations

All file operations must use REPO_PATH:

• Read: Read(REPO_PATH/filename.md) or Read("$REPO_PATH/filename.md")
• Write: Write(REPO_PATH/filename.md) or Write("$REPO_PATH/filename.md")
• Edit: Edit(REPO_PATH/filename.md) or Edit("$REPO_PATH/filename.md")
• Grep: Grep(pattern, path=REPO_PATH) or with explicit path
• Glob: Glob(pattern, path=REPO_PATH) or with explicit path

Example usage:

# Check environment variable
if [ -z "$AZKG_REPO_PATH" ]; then
  REPO_PATH=$(pwd)
else
  REPO_PATH="$AZKG_REPO_PATH"
fi

# Then use REPO_PATH for all operations
Read("$REPO_PATH/agents.md")

Concrete examples:

• If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md")
• If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg → Read("agents.md") or use full path from pwd

Task

Use Grep and Glob to calculate:

• Total notes count
• Total MOC files count
• Relationship counts by type
• Unique tag count and top 10 tags
• Notes per MOC

Execution Steps

1. Count Total Notes

Use Glob to count all markdown files (excluding MOCs):

# Count all .md files
Glob "*.md"

Filter out MOC files (files ending in _moc.md) for pure note count.

2. Count MOC Files

Use Glob to find MOC files:

# Find all MOC files
Glob "*_moc.md"

3. Count Relationships by Type

Use Grep to find each relationship type in "Related Concepts" sections:

# Count Prerequisites
Grep "### Prerequisites" --glob="*.md" --output_mode="count"

# Count Related Topics
Grep "### Related Topics" --glob="*.md" --output_mode="count"

# Count Extends
Grep "### Extends" --glob="*.md" --output_mode="count"

# Count Extended By
Grep "### Extended By" --glob="*.md" --output_mode="count"

# Count Alternatives
Grep "### Alternatives" --glob="*.md" --output_mode="count"

# Count Examples
Grep "### Examples" --glob="*.md" --output_mode="count"

For each type, also count individual relationship entries by counting lines starting with - [[ within those sections.

4. Extract and Count Tags

Use Grep to find all tags in YAML frontmatter:

# Find all tags lines
Grep "^tags: \[" --glob="*.md" --output_mode="content"

Parse out individual tags, count occurrences, and sort by frequency.

5. Calculate Additional Metrics

• Average tags per note
• Average relationships per note
• Notes without "Related Concepts" section (orphaned)
• Most connected notes (top 5 by relationship count)

Output Format

Graph Statistics
============================================================
Total notes: N
Total MOCs: M
Pure notes (excluding MOCs): X

Relationship counts:
  Prerequisites: X notes have prerequisites (Y total relationships)
  Related Topics: X notes have related topics (Y total relationships)
  Extends: X notes extend others (Y total relationships)
  Extended By: X notes are extended by others (Y total relationships)
  Alternatives: X notes have alternatives (Y total relationships)
  Examples: X notes have examples (Y total relationships)

Total relationships: Z

Tag Statistics:
  Unique tags: N
  Average tags per note: X.Y

Top 10 tags:
  #python: 25 notes
  #mcp: 18 notes
  #agents: 15 notes
  #rust: 12 notes
  #typescript: 10 notes
  ...

Graph Health:
  ✓ Well-connected notes: X (>3 relationships)
  ! Sparsely connected: Y (1-2 relationships)
  ⚠ Orphaned notes: Z (0 relationships)

Analysis and Insights

After displaying stats, provide brief analysis:

Good signs:

• Balanced relationship distribution (no single type dominates)
• High average tags per note (3-6 ideal)
• Few orphaned notes (<5%)
• Diverse tag usage (no extreme tag concentration)

Potential issues:

• Many orphaned notes → Use /expand-graph to discover relationships
• Imbalanced relationships → Consider adding missing relationship types
• Tag concentration → Some notes may need more specific tags
• Low relationship count → Graph may not be well-connected

Use Cases

• Growth tracking: Monitor note and relationship count over time
• Health check: Identify orphaned or poorly connected notes
• Tag consistency: Find most-used tags for standardization
• Balance analysis: Ensure relationship types are balanced
• Discover trends: See which domains are growing fastest

Tools Used

• Glob - Count files (notes, MOCs)
• Grep - Find relationship sections, count relationships, extract tags
• Parse logic - Extract tags from YAML, calculate statistics, sort and rank

Present Results

After displaying stats:

• Highlight any concerning metrics (too many orphaned notes, imbalanced relationships)
• Suggest actions (use /expand-graph on orphaned notes, add missing relationship types)
• Celebrate growth (if note count is increasing, congratulate user on knowledge expansion)