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

---
description: Run validation checks on the knowledge graph
---

# Validate Graph

Run validation checks on the knowledge graph to ensure integrity.

## 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

Check markdown files for:

- All wikilinks point to existing notes (no broken links)
- "Related Concepts" sections are well-formed
- Bidirectional relationships are consistent
- YAML frontmatter is valid

## Execution Steps

### 1. Find All Wikilinks

Use Grep to extract all wikilinks from all markdown files:

```bash
# Find all wikilinks in the format [[note_name]]
Grep "\[\[([^\]]+)\]\]" --glob="*.md" --output_mode="content" -n
```

Extract unique note names from results.

### 2. Verify All Wikilinks Point to Existing Files

For each unique wikilink target found:

- Use Glob to check if `target.md` exists in repository root
- Record any broken links (wikilink but no corresponding file)

### 3. Check Bidirectional Consistency

For notes with "Related Concepts" sections:

- Read notes with "Extends" relationships
- Verify target notes have "Extended By" back-reference
- Read notes with "Prerequisites" relationships
- Verify reasonable consistency (prerequisites should be foundational)

### 4. Validate YAML Frontmatter

Use Read tool to check a sample of notes:

- YAML frontmatter starts with `---` and ends with `---`
- `tags:` field is present and is an array
- Tags use lowercase-with-hyphens format

### 5. Check for Common Issues

- Notes without any "Related Concepts" section (orphaned notes)
- Notes with empty tags array
- Duplicate note filenames (shouldn't happen but check)
- MOC files that reference non-existent notes

## Output Format

**Success:**

```
Graph Validation
============================================================
[OK] Knowledge graph is valid

All checks passed:
  ✓ All wikilinks point to existing notes (N wikilinks checked)
  ✓ No broken links found
  ✓ Bidirectional relationships are consistent
  ✓ YAML frontmatter is well-formed
  ✓ No orphaned notes detected

Statistics:
  • Total notes: N
  • Total wikilinks: M
  • Total relationships: X
  • MOC files: Y
```

**Failure:**

```
Graph Validation
============================================================
[ERROR] Found N issue(s):

1. Broken wikilink: file1.md:42 references [[non_existent_note]]
2. Broken wikilink: file2.md:18 references [[another_missing]]
3. Missing inverse: agents.md extends [[semantic_routing]] but inverse not found
4. Orphaned note: lonely_note.md has no "Related Concepts" section
5. Invalid YAML: broken_note.md frontmatter is malformed

Recommendations:
  • Fix or remove broken wikilinks
  • Add "Extended By" section to semantic_routing.md
  • Consider adding relationships to lonely_note.md
  • Fix YAML frontmatter in broken_note.md
```

## Validation Rules

**Wikilink validation:**

- Every `[[note_name]]` must have corresponding `note_name.md` file
- Case-sensitive matching
- Should NOT include `.md` in wikilink (use `[[note]]` not `[[note.md]]`)

**Bidirectional validation:**

- If A extends B, then B should have "Extended By" section mentioning A
- If A is prerequisite for B, then B should mention A in "Prerequisites"
- Not always perfectly symmetric, but should be logically consistent

**YAML validation:**

- Well-formed YAML with proper delimiters
- Tags field exists and is array
- Tags follow naming convention (lowercase-with-hyphens)

**Structural validation:**

- Notes should have "Related Concepts" section (unless intentionally standalone)
- MOC files should only reference existing notes
- No circular dependencies in prerequisite chains (optional advanced check)

## If Validation Fails

For each error type, suggest fixes:

**Broken wikilinks:**

```
File: example.md:42
Issue: References [[missing_note]]
Fixes:
  • Create the missing note
  • Remove the wikilink
  • Change to reference an existing note
```

**Missing inverse relationships:**

```
File: agents.md
Issue: Extends [[semantic_routing]] but inverse not found
Fix:
  • Add to semantic_routing.md "Related Concepts" section:
    ### Extended By
    - [[agents]] - Uses routing for agent task selection
```

**Orphaned notes:**

```
File: lonely_note.md
Issue: No "Related Concepts" section
Fix:
  • Add "Related Concepts" section with at least one relationship
  • Link to appropriate MOC
  • Use /expand-graph to discover relationships
```

## Tools Used

- **Grep** - Find all wikilinks across all markdown files
- **Glob** - Check if wikilink targets exist as files
- **Read** - Read notes to check "Related Concepts" sections and YAML frontmatter
- **Parse logic** - Extract wikilinks, validate YAML, check consistency

## Success Criteria

- All wikilinks resolve to existing files
- No malformed YAML frontmatter
- Bidirectional relationships are logically consistent
- Minimal orphaned notes

## When to Run

- After creating new notes (check new relationships valid)
- After renaming notes (check wikilinks updated correctly)
- After bulk operations (check graph still consistent)
- Periodically (ensure graph health over time)