moai-workflow-jit-docs

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