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

<!-- markdownlint-disable MD029 -->

### 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**:
   ```bash
   # 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

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