Moai Workflow Jit Docs

---
name: moai-workflow-jit-docs
description: >
  Enhanced Just-In-Time document loading system that discovers, loads,
  and caches relevant documentation based on user intent and project
  context. Use when users need specific documentation on demand.
license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Grep, Glob, WebFetch, WebSearch, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
user-invocable: false
metadata:
  version: "3.0.0"
  category: "workflow"
  status: "active"
  updated: "2026-01-08"
  modularized: "false"
  tags: "workflow, documentation, jit-loading, context-aware, caching, discovery"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 5000

# MoAI Extension: Triggers
triggers:
  keywords: ["documentation", "docs", "API reference", "how to", "implement", "best practices", "technology guide", "framework documentation"]
  phases: ["plan", "run", "sync"]
  agents: ["manager-docs", "manager-spec", "expert-backend", "expert-frontend"]
---

## Quick Reference (30 seconds)

Purpose: Load relevant documentation on-demand based on user intent and context.

Primary Tools:

- WebSearch: Find latest documentation and resources online
- WebFetch: Retrieve specific documentation pages
- Context7 MCP: Access official library documentation (when available)
- Read, Grep, Glob: Search local project documentation

Trigger Patterns:

- User asks specific technical questions
- Technology keywords detected in conversation
- Domain expertise required for task completion
- Implementation guidance needed

## Implementation Guide

### Intent Detection

The system recognizes documentation needs through several patterns:

Question-Based Triggers:

- When users ask specific implementation questions (e.g., "how do I implement JWT authentication?")
- When users seek best practices or optimization guidance
- When troubleshooting questions arise

Technology-Specific Triggers:

- Detection of framework names: FastAPI, React, PostgreSQL, Docker, Kubernetes
- Detection of library names: pytest, TypeScript, GraphQL, Redis
- Detection of tool names: npm, pip, cargo, maven

Domain-Specific Triggers:

- Authentication and authorization topics
- Database and data modeling discussions
- Performance optimization inquiries
- Security-related questions

Pattern-Based Triggers:

- Implementation requests: "implement", "create", "build"
- Architecture discussions: "design", "structure", "pattern"
- Troubleshooting: "debug", "fix", "error", "not working"

### Documentation Sources

The system retrieves documentation from multiple sources in priority order:

Local Project Documentation (Highest Priority):

- Check .moai/docs/ for project-specific documentation
- Check .moai/specs/ for requirements and specifications
- Check README.md for project overview
- Check docs/ directory for comprehensive documentation

Official Documentation Sources:

- Use WebFetch to retrieve official framework documentation
- Use Context7 MCP tools when available for library documentation
- Access technology-specific official websites

Community Resources:

- Use WebSearch to find high-quality tutorials
- Search for Stack Overflow solutions with high vote counts
- Find GitHub discussions for specific issues

Real-Time Web Research:

- Use WebSearch with current year for latest information
- Search for recent best practices and updates
- Find new features and deprecation notices

### Loading Strategies

Intent Analysis Process:

- Identify technologies mentioned in user request
- Determine domain areas relevant to the question
- Classify question type (implementation, troubleshooting, conceptual)
- Assess complexity to determine documentation depth needed

Source Prioritization:

- If local documentation exists: Load project-specific docs first
- If official documentation available: Retrieve authoritative sources
- If implementation examples needed: Search community resources
- If latest information required: Perform web research

Context-Aware Caching:

- Cache retrieved documentation within session
- Maintain relevance based on current conversation context
- Remove outdated content when context shifts
- Prioritize frequently accessed documentation

### Quality Assessment

Content Quality Evaluation:

- Authority: Official sources receive highest trust
- Recency: Content within 12 months preferred for fast-moving technologies
- Completeness: Documentation with examples ranked higher
- Relevance: Match between content and user intent

Relevance Ranking:

- Calculate match between documentation content and user question
- Weight authority (30%), recency (25%), completeness (25%), relevance (20%)
- Return highest-scoring documentation first
- Indicate confidence level in retrieved information

### Practical Workflows

Authentication Implementation Workflow:

- When user asks about authentication: Detect technologies (e.g., FastAPI, JWT)
- Identify domains: authentication, security
- Load FastAPI security documentation via WebFetch
- Search for JWT best practices via WebSearch
- Provide comprehensive guidance with source attribution

Database Optimization Workflow:

- When user asks about query performance: Detect database technology
- Identify domain: performance, optimization
- Load official database documentation
- Search for optimization guides and tutorials
- Provide actionable recommendations with sources

New Technology Adoption Workflow:

- When user introduces unfamiliar technology: Detect technology name
- Load official getting started documentation
- Search for migration guides if applicable
- Find integration patterns with existing stack
- Provide strategic adoption guidance

### Error Handling

Network Failures:

- If web search fails: Fall back to cached content
- If WebFetch fails: Use local documentation if available
- Indicate partial results when some sources unreachable

Content Quality Issues:

- If retrieved content seems outdated: Search for newer sources
- If relevance unclear: Ask user for clarification
- If conflicting information found: Present multiple sources with dates

Relevance Mismatches:

- If initial search yields poor results: Refine search query
- If user context unclear: Request clarification before loading
- If documentation gap exists: Acknowledge limitation

### Performance Optimization

Caching Strategy:

- Maintain session-level cache for frequently accessed docs
- Keep project-specific documentation in memory
- Evict stale content based on access time

Efficient Loading:

- Load documentation only when explicitly needed
- Avoid preloading all possible documentation
- Use targeted searches rather than broad queries

Batch Processing:

- Combine related searches when possible
- Group documentation requests by technology
- Process multiple sources in parallel when appropriate

## Advanced Patterns

Multi-Source Aggregation:

- Combine official documentation with community examples
- Cross-reference multiple authoritative sources
- Synthesize comprehensive answers from diverse materials

Context Persistence:

- Remember documentation loaded earlier in conversation
- Avoid redundant loading of same documentation
- Build cumulative knowledge through session

Proactive Loading:

- Anticipate documentation needs based on conversation flow
- Pre-load related topics when discussing complex features
- Suggest relevant documentation before user asks

---

## Works Well With

Agents:

- workflow-docs: Documentation generation
- core-planner: Documentation planning
- workflow-spec: SPEC documentation

Skills:

- moai-docs-generation: Documentation generation
- moai-workflow-docs: Documentation validation
- moai-library-nextra: Nextra documentation

Commands:

- /moai:3-sync: Documentation synchronization
- /moai:9-feedback: Documentation improvements

<!-- moai:evolvable-start id="rationalizations" -->
## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "I already know where the docs are, JIT loading is unnecessary" | JIT docs discover context you did not know existed. Manual lookup misses cross-references. |
| "Loading all docs upfront is simpler than on-demand" | Upfront loading wastes tokens on irrelevant content. JIT loads only what matches the current intent. |
| "The cached version is recent enough" | Stale caches serve stale answers. Validate cache freshness before using cached documents. |
| "This task does not need documentation" | Every non-trivial task benefits from context. JIT docs surface relevant constraints proactively. |
| "I will find the right doc by browsing the directory" | Directory browsing is O(n). JIT matching by intent keywords is O(1) for the user. |

<!-- moai:evolvable-end -->

<!-- moai:evolvable-start id="red-flags" -->
## Red Flags

- Agent proceeds with implementation without loading any project documentation
- Cached document served when the source file was modified more recently
- Documentation loaded but not referenced in the implementation rationale
- Multiple redundant document loads in the same session (cache miss on repeated content)
- JIT loader returns zero results for a keyword that clearly maps to existing docs

<!-- moai:evolvable-end -->

<!-- moai:evolvable-start id="verification" -->
## Verification

- [ ] At least one document was loaded via JIT matching for non-trivial tasks
- [ ] Loaded documents are referenced in the agent's reasoning or output
- [ ] Cache hits validated against source file modification time
- [ ] No duplicate document loads in the same session (check load log)
- [ ] JIT trigger keywords match the user's stated intent

<!-- moai:evolvable-end -->