--- 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 ## 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. | ## 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 ## 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