gh-cubical6-melly/commands/analyze-lib-docs.md

description: Analyze library documentation and extract metadata for semantic search argument-hint: [library-name] [docs-path] allowed-tools: Task, Read, Write, Bash, Glob, Grep

Library Documentation Analysis

Analyze markdown-based library documentation and extract observations and relations for semantic search.

Arguments

• $1 - Library name (required): Name of the library (e.g., laravel, react, django)
• $2 - Documentation path (optional): Path to library docs
  • Default: knowledge-base/libraries/$1/
  • Supports absolute or relative paths

Workflow

Phase 1: Validation

1. Validate arguments:

   • Library name is required
   • If no path provided, use default: knowledge-base/libraries/$1/
   • Verify documentation path exists
   • Check for markdown files in path

2. Verify dependencies:

   • basic-memory MCP server is available
   • Validation scripts exist in plugin

Phase 2: Analysis

3. Invoke lib-doc-analyzer agent:

   Explicitly invoke the lib-doc-analyzer agent to perform the analysis:

   Use the lib-doc-analyzer agent to analyze the $1 library documentation.
   
   Agent context:
   - Library name: $1
   - Documentation path: $2 (or knowledge-base/libraries/$1/ if not specified)
   - Task: Analyze all markdown files and extract observations and relations
   - Skill: Use the lib-doc-methodology skill for guidance
   

   Alternative invocation patterns:

   Have the lib-doc-analyzer agent process the library documentation at $2.
   Extract metadata from $1 documentation using the lib-doc-analyzer agent.
   Ask lib-doc-analyzer to analyze library docs for $1 at $2.
   

   What the agent will do:

   • Automatically follow the 5-phase workflow defined in its system prompt
   • Use the lib-doc-methodology skill for extraction rules
   • Generate enhanced markdown files with frontmatter
   • Create lib-docs-$1.json metadata file
   • Run validation scripts to verify quality

4. Agent performs 5-phase workflow:

   • Discovery: Find all markdown files
   • Parsing: Extract structure (headings, code, links)
   • Analysis: Extract observations and relations
   • Generation: Create enhanced markdown files
   • Validation: Verify content preservation

Phase 3: Validation

5. Run validation scripts:

   # Validate metadata JSON
   python3 plugins/melly-writer-lib/scripts/validate-lib-docs.py lib-docs-$1.json
   
   # Verify content preservation
   python3 plugins/melly-writer-lib/scripts/validate-content.py $2
   

6. Check validation results:

   • Exit code 0: Success
   • Exit code 1: Warnings (continue with caution)
   • Exit code 2: Blocking errors (stop workflow)

Phase 4: Integration

7. Store in basic-memory:

   • Create knowledge entities for each enhanced markdown file
   • Include metadata (observations, relations) in entity
   • Generate permalinks for cross-referencing

8. Generate metadata file:

   • Create lib-docs-$1.json with complete metadata
   • Include library info, entities, relationships, statistics
   • Store in documentation path

Phase 5: Reporting

9. Generate summary report:

   ✅ Library Documentation Analysis Complete
   
   Library: [Library Name Version]
   Path: [Documentation Path]
   ---
   📊 Statistics:
     Files processed: [count]
     Observations: [count]
     Relations: [count]
     Total chunks: [count]
     Avg chunk size: [words]
   
   📁 Output:
     Enhanced files: [path]/**/*.md
     Metadata: lib-docs-[name].json
     basic-memory entities: [count] created
   
   ✅ Validation:
     Content preservation: [passed/total] passed
     Metadata quality: Valid
   
   💡 Next Steps:
     1. Search: "What is [concept] in [library]?"
     2. Build context: "Show me [library] [topic] concepts"
     3. Navigate: Open enhanced markdown files in Obsidian
   

Examples

# Analyze Laravel documentation (default path)
/melly-analyze-lib-docs laravel

# Analyze React documentation (default path)
/melly-analyze-lib-docs react

# Analyze Django with custom path
/melly-analyze-lib-docs django /path/to/django-docs

# Analyze Laravel 11.x with explicit path
/melly-analyze-lib-docs laravel-11 knowledge-base/libraries/laravel-11/

Error Handling

Missing library name:

❌ Error: Library name is required
Usage: /melly-analyze-lib-docs [library-name] [docs-path]
Example: /melly-analyze-lib-docs laravel

Documentation path not found:

❌ Error: Documentation path not found
Path: knowledge-base/libraries/[name]/
Please ensure the documentation exists or provide a custom path.

No markdown files found:

❌ Error: No markdown files found in documentation path
Path: [path]
Expected: At least one .md file in the directory

Validation failure:

❌ Validation Error: Content preservation failed
File: [filename]
Issue: Enhanced content differs from original
Action: Review agent output and try again

basic-memory unavailable:

⚠️  Warning: basic-memory MCP server not available
Analysis will continue, but entities won't be stored for semantic search.
Metadata will still be generated in lib-docs-[name].json

Output Structure

Enhanced Markdown Files

Each original markdown file is enhanced with:

• Frontmatter: Library metadata (name, version, url, file info)
• Metadata Section: Observations and relations extracted from content
• Separator: --- to separate metadata from original content
• Original Content: 100% preserved, byte-for-byte identical

Metadata JSON File

lib-docs-[library-name].json contains:

• library: Library information (name, version, url, stats)
• entities: Array of enhanced files with metadata
• relationships: Cross-file relations discovered
• analyzed_at: Timestamp of analysis

basic-memory Entities

Each enhanced markdown file becomes a searchable entity:

• Content: Original markdown content
• Metadata: Observations and relations
• Permalink: Stable reference for cross-linking

Best Practices

1. Organize documentation:

   • Use standard path: knowledge-base/libraries/[name]/
   • Keep original structure (don't flatten)
   • Preserve version information

2. Incremental updates:

   • Re-analyze when docs are updated
   • Metadata will be regenerated
   • basic-memory entities will be updated

3. Quality validation:

   • Always review validation output
   • Check content preservation results
   • Verify observations are extracted, not fabricated

4. Semantic search:

   • Use natural language queries
   • Reference concepts by name
   • Build context from multiple entities

5. Integration with C4 model:

   • Library docs inform C2 (Container) analysis
   • Technical decisions reference library capabilities
   • Architectural patterns link to library features

Troubleshooting

Agent doesn't activate

Cause: lib-doc-analyzer agent not found Solution: Ensure agent exists in plugins/melly-writer-lib/agents/

Skill not used

Cause: lib-doc-methodology skill not loaded Solution: Check plugins/melly-writer-lib/skills/lib-doc-methodology/SKILL.md exists

Validation scripts fail

Cause: Python version incompatibility or missing dependencies Solution:

• Ensure Python 3.8+ is installed: python3 --version
• Make scripts executable: chmod +x plugins/melly-writer-lib/scripts/*.py
• Install required packages (see plugin README.md)

basic-memory errors

Cause: MCP server configuration issue Solution: Verify basic-memory in ~/.claude/settings.json

Dependencies

• Agent: lib-doc-analyzer
• Skill: lib-doc-methodology
• Scripts: validate-lib-docs.py, validate-content.py
• MCP Server: basic-memory (optional but recommended)
• Python: 3.8+ with required packages

Related Commands

• /melly-init - Initialize C4 model exploration
• /melly-c2-containers - Analyze C2 containers (uses library knowledge)
• /melly-doc-c4model - Generate C4 documentation (references library docs)

---

Version: 1.0.0 Plugin: melly-writer-lib Category: knowledge-extraction