gh-witt3rd-claude-plugins-plugins-azkg/commands/learning-path.md

description

description
Generate an optimal learning sequence for a target note

Learning Path

Generate an optimal learning sequence for a target note by tracing prerequisite chains through 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

1. Parse Input

Input format: User provides:

• A note name: /learning-path mcp_security.md
• Or just the topic: /learning-path mcp_security

Normalize input:

• Add .md extension if missing
• Use Glob to verify the target note exists
• If not found, suggest similar notes using Glob

2. Load Target Note

Read the target note:

• Use Read tool to get full content
• Extract YAML tags and title
• Parse "Related Concepts" section to get prerequisites

Example:

## Related Concepts

### Prerequisites
- [[mcp_overview]] - Must understand MCP basics first
- [[oauth_fundamentals]] - OAuth is primary auth mechanism

### Related Topics
- [[api_security]] - General API security principles

3. Trace Prerequisite Chains

Algorithm: Depth-First Traversal

Starting from the target note, recursively follow prerequisite relationships:

function buildPrerequisiteTree(note, visited = new Set()):
  if note in visited:
    return []  // Cycle detection

  visited.add(note)

  // Read the note and parse "Related Concepts" → "Prerequisites"
  prerequisites = readNote(note).prerequisites

  if prerequisites is empty:
    return [note]  // Foundation reached

  tree = []
  for prereq in prerequisites:
    subtree = buildPrerequisiteTree(prereq.note, visited)
    tree.extend(subtree)

  tree.append(note)
  return tree

Implementation with tools:

1. Read target note to get prerequisites
2. For each prerequisite, Read that note to get its prerequisites
3. Recursively traverse until reaching foundation notes (no prerequisites)
4. Track visited nodes to detect cycles

Key features:

• Cycle detection: Track visited nodes to prevent infinite loops
• Multiple paths: Handle notes with multiple prerequisites
• Foundation detection: Identify notes with no prerequisites
• Depth tracking: Calculate how many levels deep each note is

4. Build Learning Sequence

Create ordered learning path:

1. Topological sort: Order notes so prerequisites always come before dependents
2. Remove duplicates: Each note appears once, at earliest possible position
3. Group by depth level: Show conceptual layers

Example structure:

Level 0 (Foundations):
- note_a.md
- note_b.md

Level 1 (Builds on foundations):
- note_c.md (requires: note_a)
- note_d.md (requires: note_b)

Level 2 (Intermediate):
- note_e.md (requires: note_c, note_d)

Level 3 (Target):
- target_note.md (requires: note_e)

5. Read Note Summaries

For each note in the learning path:

• Use Read tool to get first 3-5 lines (the summary)
• Extract the brief description after the title
• This provides context for each step

Example:

## mcp_overview.md
"Introduction to Model Context Protocol, a standardized way for AI assistants to connect to data sources and tools."

6. Analyze Learning Path

Calculate metrics:

Path statistics:

• Total notes in sequence: N
• Depth levels: M (foundation to target)
• Estimated reading time: N × 10 minutes = X minutes
• Foundational notes: Count of level 0 notes
• Branching factor: Average prerequisites per note

Complexity assessment:

• Simple path (1-3 notes): "Quick learning path"
• Moderate path (4-7 notes): "Intermediate learning sequence"
• Complex path (8+ notes): "Comprehensive learning journey"

Identify critical concepts:

• Notes that multiple paths converge through
• "Bottleneck" concepts that are prerequisites for many others

7. Suggest Related Learning

Enrich the path with optional content:

Parallel reading (Related Topics):

• Read "Related Topics" sections from notes in path
• Notes at same level that provide additional context
• Not strictly required but enhance understanding

Deeper dives (Extended By):

• Read "Extended By" sections from notes in path
• Advanced topics that build on concepts in the path
• "After mastering this path, explore..."

Alternative approaches (Alternatives):

• Read "Alternatives" sections from notes in path
• Different ways to achieve similar understanding
• "For a different perspective, consider..."

Practical examples (Examples):

• Read "Examples" sections from notes in path
• Concrete implementations to solidify understanding
• "Apply these concepts with..."

8. Generate Output

Format the learning path:

# Learning Path: [Target Note Title]

🎯 **Goal:** Understand [target topic]
📚 **Total Notes:** N notes across M levels
⏱️  **Estimated Time:** X minutes
🏗️  **Complexity:** [Simple|Moderate|Complex]

---

## Prerequisites Sequence

### Level 0: Foundations
Start here if you're new to this topic.

1. **[[note_a]]** (5 min read)
   Brief description from note.
   *Why it's needed:* Foundation for understanding [concept]

2. **[[note_b]]** (8 min read)
   Brief description from note.
   *Why it's needed:* Introduces core [concept]

### Level 1: Core Concepts
Once you understand the foundations, proceed here.

3. **[[note_c]]** (10 min read)
   Brief description from note.
   *Builds on:* note_a
   *Why it's needed:* Extends [concept] with [new idea]

4. **[[note_d]]** (7 min read)
   Brief description from note.
   *Builds on:* note_b
   *Why it's needed:* Applies [concept] to [domain]

### Level 2: Integration
Combining concepts from previous levels.

5. **[[note_e]]** (12 min read)
   Brief description from note.
   *Builds on:* note_c, note_d
   *Why it's needed:* Synthesizes [concepts] for [purpose]

### Level 3: Target Concept
Your destination!

6. **[[target_note]]** (15 min read)
   Brief description from note.
   *Builds on:* note_e
   *This is your goal:* Complete understanding of [target topic]

---

## Optional Enrichment

### Parallel Reading (Same Level)
Enhance understanding at each level:
- **[[related_a]]** - Provides additional context on [concept]
- **[[related_b]]** - Alternative perspective on [concept]

### Go Deeper (Beyond Target)
After mastering this path:
- **[[advanced_a]]** - Builds on target with [advanced concept]
- **[[advanced_b]]** - Applies target to [specific domain]

### Practical Applications
See these concepts in action:
- **[[example_a]]** - Real implementation of [concept]
- **[[example_b]]** - Case study using [concept]

### Alternative Paths
Different approaches to similar understanding:
- **[[alternative_a]]** - [Different approach] to achieving similar goals

---

## Critical Concepts

These notes are central to this learning path:
- **[[critical_note]]** - Required by X other notes in this path

---

## Visual Path

Foundations Core Concepts Integration Target ───────────── ───────────── ─────────── ──────

note_a ──────────┐ ├──> note_c ────────┐ │ │ note_b ──────────┴──> note_d ────────┴──> note_e ──> target_note

---

## Next Steps

1. **Start with Level 0** if concepts are new
2. **Skip familiar sections** if you have background knowledge
3. **Use `/graph-note`** to inspect relationships for each note
4. **Use `/expand-graph`** to discover more connections
5. **Review in Obsidian** for visual graph navigation

**Pro tip:** Open multiple notes in tabs and read through the sequence in order!

9. Handle Edge Cases

No prerequisites:

Learning Path: [Target Note]

✅ This note has no prerequisites!

This is a foundational concept that can be learned directly.
No background knowledge required.

**Estimated reading time:** X minutes

**What builds on this:**
After understanding this note, you can explore:
- [[note_x]] - Extends this concept
- [[note_y]] - Applies this concept

Circular dependencies:

⚠️ Circular Dependency Detected

The following notes form a dependency cycle:
- [[note_a]] requires [[note_b]]
- [[note_b]] requires [[note_c]]
- [[note_c]] requires [[note_a]]

**Suggested reading order:**
Read these notes together as an interconnected group:
1. [[note_a]] - Brief overview
2. [[note_b]] - Builds on understanding from note_a
3. [[note_c]] - Completes the cycle
4. Re-read all three for full understanding

**Action needed:** Consider refactoring these notes to break the cycle.
Use `/graph-validate` to check for more circular dependencies.

Very long path (>15 notes):

📚 Complex Learning Path Detected

This path contains N notes across M levels.

**Suggested approach:**
- Break into smaller milestones
- Focus on one level at a time
- Take breaks between levels
- Consider creating intermediate checkpoints

**Milestones:**
🎯 Milestone 1: Foundations (Notes 1-5)
🎯 Milestone 2: Core Concepts (Notes 6-10)
🎯 Milestone 3: Advanced Topics (Notes 11-15)
🎯 Milestone 4: Target Mastery (Notes 16-N)

10. Provide Summary Stats

Output concise metrics:

Learning Path Summary
━━━━━━━━━━━━━━━━━━━━━

📊 Path Metrics:
- Total notes: N
- Depth levels: M
- Estimated time: X minutes
- Foundation notes: Y
- Average prerequisites per note: Z

🎯 Complexity: [Simple|Moderate|Complex]

💡 Key Insight: [Most important observation about this path]

🔗 Critical Concept: [Note that appears most frequently as prerequisite]

Tools Used

• Read - Get note content, parse "Related Concepts" sections, extract summaries
• Glob - Verify notes exist, find similar notes if target not found
• Parse logic - Traverse prerequisite chains, topological sort, depth calculation
• Graph traversal - Depth-first search with cycle detection

Important Notes

Quality guidelines:

• Clear level progression
• Justify why each prerequisite is needed
• Provide time estimates (realistic reading + comprehension)
• Make path scannable with good formatting
• Include visual representation when helpful
• Handle edge cases gracefully

User experience:

• Make it easy to start learning immediately
• Show progress milestones
• Suggest checkpoints for complex paths
• Provide escape hatches (skip, alternative paths)
• Encourage practical application

Graph integrity:

• Report any issues found (cycles, broken links)
• Suggest graph improvements
• Validate prerequisite chains make semantic sense
• Use /graph-validate to check bidirectionality

Execute the learning path generation for the note provided by the user.