gh-rafaelcalleja-claude-market-place-plugins-claudekit-skills/skills/docs-seeker/WORKFLOWS.md

# Detailed Workflows & Examples

This document provides comprehensive workflow examples for the docs-seeker skill.

## Parallel Exploration Strategy

### When to Use Multiple Agents

Deploy parallel agents when:
- llms.txt contains more than 3 URLs
- Repository has multiple documentation directories
- Need to check multiple versions
- Comprehensive coverage required

### How to Launch Parallel Agents

Use Task tool with `Explore` subagent:

```markdown
Example for 5 URLs:
1. Launch all 5 Explore agents in single message
2. Each agent gets specific URLs to read
3. Each agent extracts relevant information
4. Wait for all agents to complete
5. Aggregate results
```

### Agent Distribution Guidelines

**Small documentation sets (1-3 URLs):**
- Deploy 2 Explore agents to handle all URLs
- Simple, straightforward extraction
- Fastest for small amounts

**Medium documentation sets (4-10 URLs):**
- Deploy 3-6 Explore agents
- Balance workload evenly
- Group related URLs together

**Large documentation sets (11+ URLs):**
- Deploy 7-15 Explore agents (max)
- Prioritize most relevant URLs first
- Group related URLs together
- Balance workload evenly
- Avoid over-parallelization

### Best Distribution Practices

1. **Group related content**: Keep related URLs with same agent
2. **Balance workload**: Distribute URLs evenly by estimated size
3. **Prioritize critical docs**: Assign core docs first
4. **Avoid over-parallelization**: Max 7 agents to avoid overwhelming
5. **Sequential batches**: For 15+ URLs, use two sequential batches

## Workflow Examples

### Example 1: Library with llms.txt (Simple)

**Scenario**: User requests documentation for Astro

```
Step 1: Initial Search (PRIORITIZE context7.com)
→ Try context7.com first: https://context7.com/withastro/astro/llms.txt
→ WebFetch: Read llms.txt content
→ Result: Contains 8+ documentation URLs (success!)

Alternative if context7.com fails:
→ WebSearch: "Astro llms.txt site:docs.astro.build"
→ Result: https://docs.astro.build/llms.txt found

Step 2: Process llms.txt
→ Already fetched in Step 1
→ Result: Contains 8 documentation URLs

Step 3: Parallel Exploration
→ Launch 3 Explorer agents simultaneously:

  Agent 1 (URLs 1-3):
  - https://docs.astro.build/en/getting-started/
  - https://docs.astro.build/en/install/
  - https://docs.astro.build/en/editor-setup/

  Agent 2 (URLs 4-6):
  - https://docs.astro.build/en/core-concepts/project-structure/
  - https://docs.astro.build/en/core-concepts/astro-components/
  - https://docs.astro.build/en/core-concepts/layouts/

  Agent 3 (URLs 7-8):
  - https://docs.astro.build/en/guides/configuring-astro/
  - https://docs.astro.build/en/reference/configuration-reference/

Step 4: Aggregate Findings
→ Collect results from all 3 agents
→ Synthesize into cohesive documentation

Step 5: Present Report
→ Format using standard output structure
→ Include source attribution
→ Note any gaps or limitations
```

### Example 2: Library without llms.txt on context7 (Repository Analysis)

**Scenario**: User requests documentation for obscure library

```
Step 1: Try context7.com first
→ Attempt: https://context7.com/org/library-name/llms.txt
→ Result: Not found (404)

Step 2: Find GitHub Repository
→ WebSearch: "[library-name] github repository"
→ Result: https://github.com/org/library-name

Step 2a: Try context7.com with GitHub info
→ Attempt: https://context7.com/org/library-name/llms.txt
→ Result: Still not found

Step 3: Verify Repository
→ Check if it's official/active
→ Note star count, last update, license

Step 4: Check Repomix Installation
→ Bash: which repomix || npm install -g repomix

Step 5: Clone and Process Repository
→ Bash: git clone https://github.com/org/library-name /tmp/docs-analysis
→ Bash: cd /tmp/docs-analysis && repomix --output repomix-output.xml

Step 6: Analyze Repomix Output
→ Read: /tmp/docs-analysis/repomix-output.xml
→ Extract sections: README, docs/, examples/, CONTRIBUTING.md

Step 7: Present Findings
→ Format extracted documentation
→ Highlight key sections: installation, usage, API, examples
→ Note repository health: stars, activity, issues
```

### Example 3: Topic-Specific Search (context7.com feature)

**Scenario**: User asks "How do I use the date picker in shadcn/ui?"

```
Step 1: Identify library and topic
→ Library: shadcn/ui
→ Topic: date picker

Step 2: Construct context7.com URL with topic parameter
→ URL: https://context7.com/shadcn-ui/ui/llms.txt?topic=date
→ WebFetch: Read filtered content
→ Result: Returns ONLY date-related documentation (highly targeted!)

Step 3: Present Findings
→ Focused documentation on date picker component
→ Installation instructions
→ Usage examples
→ API reference for date components
→ Much faster than reading entire documentation

Benefits of topic search:
- Reduces context usage (only relevant docs loaded)
- Faster results (no need to filter manually)
- More accurate (context7 filters for you)
```

### Example 4: Multiple Versions Comparison

**Scenario**: User wants to compare v1 and v2 documentation

```
Step 1: Identify Version Requirements
→ User needs: v1.x and v2.x comparison
→ Primary focus: migration path and breaking changes

Step 2: Search Both Versions
→ WebSearch: "[library] v1 llms.txt"
→ WebSearch: "[library] v2 llms.txt"

Step 3: Launch Parallel Version Analysis
→ Deploy two sets of Explorer agents:

  Set A - v1 Documentation (3 agents):
  Agent 1: Core concepts v1
  Agent 2: API reference v1
  Agent 3: Examples v1

  Set B - v2 Documentation (3 agents):
  Agent 4: Core concepts v2
  Agent 5: API reference v2
  Agent 6: Examples v2

Step 4: Compare Findings
→ Analyze differences in:
  - Core concepts changes
  - API modifications
  - Breaking changes
  - New features in v2
  - Deprecated features from v1

Step 5: Present Side-by-Side Analysis
→ Migration guide format:
  - What changed
  - What's new
  - What's deprecated
  - Migration steps
  - Code examples (before/after)
```

### Example 4: No Official Documentation (Research Fallback)

**Scenario**: Library with scattered documentation

```
Step 1: Exhaust Structured Sources
→ WebSearch: llms.txt (not found)
→ WebSearch: GitHub repo (not found or no docs)
→ WebSearch: Official website (minimal content)

Step 2: Deploy Researcher Agents
→ Launch 4 Researcher agents in parallel:

  Researcher 1: Official sources
  - Package registry page (npm, PyPI, etc.)
  - Official website
  - Release notes

  Researcher 2: Tutorial content
  - Blog posts
  - Getting started guides
  - Video tutorials

  Researcher 3: Community resources
  - Stack Overflow discussions
  - Reddit threads
  - GitHub issues/discussions

  Researcher 4: API & reference
  - Auto-generated docs
  - Code examples in wild
  - Community examples

Step 3: Aggregate Diverse Sources
→ Collect findings from all researchers
→ Cross-reference information
→ Identify consistent patterns
→ Note conflicting information

Step 4: Present Consolidated Report
→ Structure findings:
  - Overview (from multiple sources)
  - Installation (verified approach)
  - Basic usage (community examples)
  - Common patterns (from discussions)
  - Known issues (from GitHub/SO)
  - Caveats about source quality
```

### Example 5: Large Documentation Set (Two-Phase)

**Scenario**: Framework with 20+ documentation pages

```
Step 1: Analyze Documentation Structure
→ WebFetch: llms.txt
→ Result: Contains 24 URLs across multiple categories

Step 2: Prioritize URLs
→ Categorize by importance:
  - Critical (8): Getting started, core concepts, API
  - Important (10): Guides, integrations, examples
  - Supplementary (6): Advanced topics, internals

Step 3: Phase 1 - Critical Documentation
→ Launch 5 Explorer agents:
  Agent 1: URLs 1-2 (Getting started)
  Agent 2: URLs 3-4 (Installation & setup)
  Agent 3: URLs 5-6 (Core concepts)
  Agent 4: URLs 7-8 (Basic API)
  Agent 5: URL 9 (Configuration)

→ Wait for completion
→ Quick review of coverage

Step 4: Phase 2 - Important Documentation
→ Launch 5 Explorer agents:
  Agent 6: URLs 10-11 (Routing guide)
  Agent 7: URLs 12-13 (Data fetching)
  Agent 8: URLs 14-15 (Authentication)
  Agent 9: URLs 16-17 (Deployment)
  Agent 10: URLs 18-19 (Integrations)

Step 5: Evaluate Need for Phase 3
→ Assess user needs
→ If supplementary topics required:
  - Launch final batch for advanced topics
→ If basics sufficient:
  - Note additional resources in report

Step 6: Comprehensive Report
→ Synthesize all phases
→ Organize by topic
→ Cross-reference related sections
→ Highlight critical workflows
```

## Performance Optimization Strategies

### Minimize Sequential Operations

**Bad approach:**
```
1. Read URL 1 with WebFetch
2. Wait for result
3. Read URL 2 with WebFetch
4. Wait for result
5. Read URL 3 with WebFetch
6. Wait for result
Time: 3x single URL fetch time
```

**Good approach:**
```
1. Launch 3 Explorer agents simultaneously
2. Each reads one URL
3. All complete in parallel
4. Aggregate results
Time: ~1x single URL fetch time
```

### Batch Related Operations

**Group by topic:**
```
Agent 1: Authentication (login.md, oauth.md, sessions.md)
Agent 2: Database (models.md, queries.md, migrations.md)
Agent 3: API (routes.md, middleware.md, validation.md)
```

**Group by content type:**
```
Agent 1: Tutorials (getting-started.md, quickstart.md)
Agent 2: Reference (api-ref.md, config-ref.md)
Agent 3: Guides (best-practices.md, troubleshooting.md)
```

### Use Caching Effectively

**Repository analysis:**
```
1. First request: Clone + Repomix (slow)
2. Save repomix-output.xml
3. Subsequent requests: Reuse saved output (fast)
4. Refresh only if repository updated
```

**llms.txt content:**
```
1. First fetch: WebFetch llms.txt
2. Store URL list in session
3. Reuse for follow-up questions
4. Re-fetch only if user changes version
```

### Fail Fast Strategy

**Set timeouts:**
```
1. WebSearch: 30 seconds max
2. WebFetch: 60 seconds max
3. Repository clone: 5 minutes max
4. Repomix processing: 10 minutes max
```

**Quick fallback:**
```
1. Try llms.txt (30 sec timeout)
2. If fails → immediately try repository
3. If fails → immediately launch researchers
4. Don't retry failed methods
```

## Common Pitfalls & Solutions

### Pitfall 1: Over-Parallelization

**Problem**: Launching 15 agents at once
**Impact**: Slow, overwhelming, hard to track
**Solution**: Max 7 agents per batch, use phases for large sets

### Pitfall 2: Unbalanced Workload

**Problem**: Agent 1 gets 1 URL, Agent 2 gets 10 URLs
**Impact**: Agent 1 finishes fast, Agent 2 bottleneck
**Solution**: Distribute evenly or by estimated size

### Pitfall 3: Ignoring Errors

**Problem**: Agent fails, continue without checking
**Impact**: Incomplete documentation, missing sections
**Solution**: Check all agent outputs, retry or note failures

### Pitfall 4: Poor Aggregation

**Problem**: Concatenating agent outputs without synthesis
**Impact**: Redundant, disorganized information
**Solution**: Synthesize findings, organize by topic, deduplicate

### Pitfall 5: Not Verifying Sources

**Problem**: Using first result without verification
**Impact**: Outdated or unofficial documentation
**Solution**: Check official status, version, date

## Decision Trees

### Choosing Documentation Strategy

```
Start
  ↓
Does llms.txt exist?
  ↓
YES → How many URLs?
  ↓
  1-3 URLs → Single WebFetch/Explorer
  4+ URLs → Parallel Explorers
  ↓
NO → Is there GitHub repo?
  ↓
  YES → Is Repomix feasible?
    ↓
    YES → Use Repomix
    NO → Manual exploration with Explorers
  ↓
  NO → Deploy Researcher agents
```

### Choosing Agent Count

```
URL Count < 3
  ↓
Single Explorer
  ↓
URL Count 4-10
  ↓
3-5 Explorers
  ↓
URL Count 11-20
  ↓
5-7 Explorers (or two phases)
  ↓
URL Count > 20
  ↓
Two-phase approach:
  Phase 1: 5 agents (critical)
  Phase 2: 5 agents (important)
```

## Advanced Scenarios

### Scenario: Multi-Language Documentation

**Challenge**: Documentation in multiple languages

**Approach**:
1. Identify target language from user
2. Search for language-specific llms.txt
3. If not found, search for English version
4. Note language limitations in report
5. Offer to translate key sections if needed

### Scenario: Framework with Plugins

**Challenge**: Core framework + 50 plugin docs

**Approach**:
1. Focus on core framework first
2. Ask user which plugins they need
3. Launch targeted search for specific plugins
4. Avoid trying to document everything
5. Note available plugins in report

### Scenario: Documentation Under Construction

**Challenge**: New release with incomplete docs

**Approach**:
1. Note documentation status upfront
2. Combine available docs with repository analysis
3. Check GitHub issues for documentation requests
4. Provide code examples from tests/examples
5. Clearly mark sections as "inferred from code"

### Scenario: Conflicting Information

**Challenge**: Multiple sources with different approaches

**Approach**:
1. Identify primary official source
2. Note version differences between sources
3. Present both approaches with context
4. Recommend official/latest approach
5. Explain why conflict exists (e.g., version change)