From 2ecf2ce5adeee205261680682083b0a324e62463 Mon Sep 17 00:00:00 2001 From: Hannes Rudolph Date: Thu, 3 Jul 2025 12:50:09 -0600 Subject: [PATCH] feat: improve docs-extractor mode rules for better documentation extraction (#5381) - Enhanced extraction workflow with clearer step-by-step instructions - Improved documentation patterns for better structure recognition - Refined analysis techniques for comprehensive coverage - Updated tool usage guide with practical examples - Added complete extraction examples for common scenarios - Improved communication guidelines for clearer output - Enhanced user-friendly examples with better formatting --- .../1_extraction_workflow.xml | 184 +++++----- .../2_documentation_patterns.xml | 344 ++++++++---------- .../3_analysis_techniques.xml | 206 ++++------- .../4_tool_usage_guide.xml | 166 ++++----- .../5_complete_extraction_examples.xml | 55 ++- .../6_communication_guidelines.xml | 272 ++++++-------- .../7_user_friendly_examples.xml | 252 ++++++------- 7 files changed, 641 insertions(+), 838 deletions(-) diff --git a/.roo/rules-docs-extractor/1_extraction_workflow.xml b/.roo/rules-docs-extractor/1_extraction_workflow.xml index 6cac8da27a..936cba7edd 100644 --- a/.roo/rules-docs-extractor/1_extraction_workflow.xml +++ b/.roo/rules-docs-extractor/1_extraction_workflow.xml @@ -1,30 +1,28 @@ - The Docs Extractor mode performs comprehensive analysis of features and components - to generate multi-audience documentation. It extracts technical details, business logic, - user workflows, and all related information to create documentation suitable for - end-users, developers, administrators, and stakeholders. + The Docs Extractor mode analyzes features to generate documentation. + It extracts technical details, business logic, and user workflows + for different audiences. - Understand Documentation Request + Parse Request - Parse the user's request to identify the feature or component. - Determine if the user has provided a documentation section for review or is requesting new documentation. - Default to user-friendly documentation unless technical docs are specifically requested. - Focus on practical benefits and real-world usage. - Note any specific aspects the user wants emphasized. + Identify the feature or component in the user's request. + Determine if the request is for a review or to generate new documentation. + Default to user-friendly docs unless technical output is requested. + Note any specific areas to emphasize. - The user will specify what they want documented in their initial message. The workflow branches based on whether a review is requested or new documentation is to be generated. + The initial request determines the workflow path (review vs. generation). - Initial Feature Discovery + Discover Feature - Use semantic search to find all related code - Identify entry points and main components - Map high-level architecture + Find related code with semantic search. + Identify entry points and components. + Map the high-level architecture. @@ -36,32 +34,32 @@ - Technical Implementation Analysis + Code Analysis - Analyze source code structure + Analyze code structure
- - Identify classes, functions, and modules - - Extract method signatures and parameters - - Document return types and data structures - - Map inheritance and composition relationships + - Identify classes, functions, modules + - Extract method signatures, parameters + - Document return types, data structures + - Map inheritance and composition
- Extract API specifications + Extract APIs
- - REST endpoints with methods and parameters - - GraphQL schemas and resolvers - - WebSocket events and handlers - - RPC interfaces and protocols + - REST endpoints + - GraphQL schemas + - WebSocket events + - RPC interfaces
- Document configuration options + Document configuration
- Environment variables - - Configuration files and schemas - - Feature flags and toggles + - Config files and schemas + - Feature flags - Runtime parameters
@@ -69,78 +67,78 @@ - Business Logic and Workflow Extraction + Business Logic Extraction - Map user workflows + Map workflows
- - User journey through the feature - - Decision points and branching logic - - State transitions and lifecycle - - User roles and permissions + - User journey + - Decision points and branching + - State transitions + - Roles and permissions
Document business rules
- - Validation logic and constraints - - Calculation formulas and algorithms + - Validation logic + - Formulas and algorithms - Business process implementations - - Compliance and regulatory requirements + - Compliance requirements
Identify use cases
- - Primary use cases and scenarios - - Edge cases and special conditions - - Error scenarios and recovery - - Performance considerations + - Primary use cases + - Edge cases + - Error scenarios + - Performance factors
- Dependencies and Integration Analysis + Dependency Analysis - Map external dependencies + Map dependencies
- - Third-party libraries and versions + - Third-party libraries - External services and APIs - - Database connections and schemas - - Message queues and event systems + - Database connections + - Message queues
Document integration points
- - Incoming webhooks and callbacks + - Incoming webhooks - Outgoing API calls - - Event publishers and subscribers - - Shared data stores and caches + - Event publishers/subscribers + - Shared data stores
Analyze data flow
- - Input data sources and formats - - Data transformations and mappings + - Data sources and formats + - Data transformations - Output formats and destinations - - Data retention and lifecycle + - Data retention policies
- Quality and Testing Analysis + Test Analysis Assess test coverage
- - Unit test coverage and quality + - Unit test coverage - Integration test scenarios - End-to-end test flows - Performance test results @@ -150,7 +148,7 @@ Document error handling
- Error types and codes - - Exception handling strategies + - Exception handling - Fallback mechanisms - Recovery procedures
@@ -158,43 +156,43 @@ Identify quality metrics
- - Code complexity metrics + - Code complexity - Performance benchmarks - - Security vulnerability assessments - - Maintainability indices + - Security vulnerabilities + - Maintainability scores
- Security and Compliance Analysis + Security Analysis - Document security measures + Document security
- - Authentication mechanisms - - Authorization and access control - - Data encryption methods - - Security headers and policies + - Auth mechanisms + - Access control + - Data encryption + - Security policies
Identify vulnerabilities
- Known security issues - - Potential attack vectors - - Mitigation strategies - - Security best practices + - Attack vectors + - Mitigation + - Best practices
- Compliance requirements + Check compliance
- - Regulatory compliance (GDPR, HIPAA, etc.) - - Industry standards adherence + - Regulatory compliance (GDPR, etc.) + - Industry standards - Audit trail requirements - - Data privacy considerations + - Data privacy
@@ -202,37 +200,37 @@ - This phase has two paths: Reviewing existing docs or Generating new docs. The path taken is determined in the initialization phase. + Workflow branches here: review existing docs or generate new docs. - Path 1: Review and Recommend Improvements - This path is followed if the user provided a documentation section for review. + Path 1: Review and Recommend + Used when a document is provided for review. - Compare the provided documentation against the analysis of the codebase. - Identify inaccuracies (technical, logical), omissions, and areas for improvement. - Categorize inaccuracies by severity (e.g., Critical, Major, Minor, Suggestion). - Formulate a structured recommendation in the chat, suitable for being copied to the docs team. - Do not write any files or make changes yourself. - The final output in the chat should ONLY be the structured recommendation, without any preceding conversational text. + Compare provided docs against codebase analysis. + Identify inaccuracies, omissions, and areas for improvement. + Categorize issues by severity (Critical, Major, Minor). + Formulate a structured recommendation in chat. + Do not write files. + Final output is only the recommendation. - Path 2: Generate New Documentation - This path is followed if the user requested new documentation. + Path 2: Generate Documentation + Used when new documentation is requested. - Choose a documentation style (e.g., user-focused or comprehensive) from `2_documentation_patterns.xml`. - Structure the documentation with clear sections, examples, and user-friendly elements. - Create a `DOCS-TEMP-[feature].md` file with the generated content. - Use a conversational tone and practical examples from `7_user_friendly_examples.xml`. + Select a template from `2_documentation_patterns.xml`. + Structure the document with clear sections and examples. + Create `DOCS-TEMP-[feature].md` with generated content. + Apply tone and examples from `7_user_friendly_examples.xml`. - All code paths have been analyzed - Business logic is fully documented - Integration points are mapped - Security considerations are addressed - Documentation serves all target audiences - Metadata and cross-references are complete + Code paths analyzed + Business logic documented + Integration points mapped + Security addressed + Audience needs met + Metadata and links are complete \ No newline at end of file diff --git a/.roo/rules-docs-extractor/2_documentation_patterns.xml b/.roo/rules-docs-extractor/2_documentation_patterns.xml index 32fc236feb..ef1643d8a4 100644 --- a/.roo/rules-docs-extractor/2_documentation_patterns.xml +++ b/.roo/rules-docs-extractor/2_documentation_patterns.xml @@ -1,287 +1,255 @@ - Standard patterns and templates for structuring extracted documentation - to serve end-users with clear, practical information. + Standard templates for structuring extracted documentation. - - + + - + - - Between major sections + --- - Improve readability and scanning - + Separate sections. + - + - + - - Show real tool output or interface elements - Use actual file paths and settings names - Include common error messages and solutions - + + Show tool output or UI elements. + Use actual file paths and setting names. + Include common errors and solutions. + - - - - - + - + - + - - + + - - - - Step-by-step tutorials with screenshots - Common use case examples - Troubleshooting guides for user errors - Feature benefits and value propositions - - - Use simple, non-technical language - Include visual aids and examples - Focus on outcomes rather than implementation - Provide clear action steps - + + + + Tutorials + Use cases + Troubleshooting + Benefits + + - - - Code examples and snippets - API specifications and contracts - Integration patterns and best practices - Performance optimization techniques - - - Use precise technical terminology - Include code samples in multiple languages - Document edge cases and limitations - Provide debugging and testing guidance - + + + Code examples + API specs + Integration patterns + Performance + + - - - Deployment and configuration procedures - Monitoring and maintenance tasks - Security hardening guidelines - Backup and disaster recovery - - - Focus on operational aspects - Include command-line examples - Document automation opportunities - Emphasize security and compliance - + + + Deployment + Monitoring + Security hardening + Backup and recovery + + - - - Business value and ROI - Feature capabilities and limitations + + + Business value + Capabilities and limits Competitive advantages - Risk assessment and mitigation - - - Use business-oriented language - Include metrics and KPIs - Focus on strategic benefits - Provide executive summaries - + Risk assessment + + - + diff --git a/.roo/rules-docs-extractor/3_analysis_techniques.xml b/.roo/rules-docs-extractor/3_analysis_techniques.xml index 149b554599..4ab4cb17cc 100644 --- a/.roo/rules-docs-extractor/3_analysis_techniques.xml +++ b/.roo/rules-docs-extractor/3_analysis_techniques.xml @@ -1,19 +1,18 @@ - Comprehensive techniques for analyzing code and extracting documentation-worthy - information from various aspects of a codebase. + Techniques for analyzing code to extract documentation. - Identify and analyze main entry points to understand feature flow + Analyze entry points to understand feature flow. - Search for main functions, controllers, or route handlers - Trace execution flow from entry to exit - Map decision branches and conditionals - Document input validation and preprocessing + Find main functions, controllers, or route handlers. + Trace execution flow. + Map decision branches. + Document input validation. @@ -36,7 +35,7 @@ - Extract API specifications from code implementations + Extract API specifications from code. @@ -46,10 +45,8 @@ - HTTP method - Route path - - Path parameters - - Query parameters - - Request body schema - - Response schemas + - Path/query parameters + - Request/response schemas - Status codes @@ -58,9 +55,8 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) ]]> - - Schema types + - Schema and input types - Resolvers - - Input types - Return types - Field arguments @@ -70,15 +66,15 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) - Map all dependencies and integration points + Map dependencies and integration points. - Import statements and require calls - Package.json dependencies + Import/require statements + package.json dependencies External API calls - Database connections + DB connections Message queue integrations - File system operations + Filesystem operations @@ -102,31 +98,22 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) - Extract data models, schemas, and type definitions + Extract data models, schemas, and type definitions. - - interface definitions - - type aliases - - class declarations - - enum definitions + - interfaces, types, classes, enums - - Schema definitions - - Migration files - - Model definitions (ORM) - - SQL CREATE statements + - Schema definitions, migration files, ORM models - - JSON Schema - - Joi/Yup schemas - - Validation decorators - - Custom validators + - JSON Schema, Joi/Yup/Zod schemas, validation decorators @@ -147,37 +134,33 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) - Identify and document business rules and logic + Identify and document business rules. - Complex conditional statements + Complex conditionals Calculation functions Validation rules State machines - Business-specific constants - Domain-specific algorithms + Domain-specific constants and algorithms - Why the logic exists (business requirement) - When the logic applies (conditions) - What the logic does (transformation) - Edge cases and exceptions - Business impact of changes + Why logic exists (business need) + When logic applies (conditions) + What logic does (transformation) + Edge cases + Impact of changes - Document error handling strategies and recovery mechanisms + Document error handling and recovery. - Try-catch blocks and error boundaries - Custom error classes and types + try/catch blocks, error boundaries + Custom error classes Error codes and messages - Logging strategies - Fallback mechanisms - Retry logic - Circuit breakers + Logging, fallbacks, retries, circuit breakers @@ -196,81 +179,68 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) - Identify security measures and potential vulnerabilities + Identify security measures and vulnerabilities. - - JWT implementation - - Session management - - OAuth flows - - API key handling + - JWT, sessions, OAuth, API keys - - Role-based access control - - Permission checks - - Resource ownership validation - - Access control lists + - RBAC, permission checks, ownership validation - - Encryption usage - - Hashing algorithms - - Sensitive data handling - - PII protection + - Encryption, hashing, sensitive data handling - - Input sanitization - - SQL injection prevention - - XSS protection - - CSRF tokens - + - Sanitization, SQLi/XSS/CSRF prevention + - Identify performance characteristics and optimization opportunities + Identify performance factors and optimization opportunities. - Database query patterns (N+1 queries) + DB query patterns (N+1) Caching strategies - Async/await usage + Async usage Batch processing Resource pooling Memory management Algorithm complexity - Time complexity of algorithms - Space complexity - Database query counts + Time/space complexity + DB query counts API response times - Memory usage patterns - Concurrent request handling + Memory usage + Concurrency handling - Analyze test coverage and quality + Analyze test coverage. - + __tests__, *.test.ts, *.spec.ts - Function-level coverage + Function coverage - + integration/, e2e/ - Feature workflow coverage + Workflow coverage - + api-tests/, *.api.test.ts Endpoint coverage @@ -293,20 +263,16 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) - Extract all configuration options and their impacts + Extract configuration options and their impacts. - Environment variables (.env files) - Configuration files (config.json, settings.yml) - Command-line arguments - Feature flags - Build-time constants + .env files, config files, CLI args, feature flags Default values - Valid value ranges - Impact on behavior - Dependencies between configs + Valid values + Behavior impact + Config dependencies Security implications @@ -315,40 +281,29 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) - Map complete user workflows through the feature + Map user workflows through the feature. - Identify user entry points (UI, API, CLI) - Trace user actions through the system - Document decision points and branches - Map data transformations at each step - Identify exit points and outcomes + Identify entry points (UI, API, CLI). + Trace user actions. + Document decision points. + Map data transformations. + Identify outcomes. - User flow diagrams - Step-by-step procedures - Decision trees - State transition diagrams + Flow diagrams, procedures, decision trees, state diagrams. - Document how the feature integrates with other systems + Document integration with other systems. - Synchronous API calls - Asynchronous messaging - Event-driven interactions - Batch processing - Real-time streaming + Sync API calls, async messaging, events, batch processing, streaming. - Integration protocols and formats - Authentication mechanisms - Error handling and retries - Data transformation requirements - SLA and performance expectations + Protocols, auth, error handling, data transforms, SLAs. @@ -356,10 +311,7 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) - Package.json engines field - README compatibility sections - Migration guides - Breaking change documentation + package.json, READMEs, migration guides, breaking changes docs. @@ -372,16 +324,10 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) - @deprecated annotations - TODO: deprecate comments - Legacy code markers - Migration warnings + @deprecated, TODO comments, legacy code markers. - Deprecation date - Removal timeline - Migration path - Alternative solutions + Deprecation date, removal timeline, migration path, alternatives. @@ -389,21 +335,17 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver) - All public APIs documented - Examples provided for complex features - Error scenarios covered - Configuration options explained - Security considerations addressed + Public APIs documented. + Examples for complex features. + Error scenarios covered. + Config options explained. + Security addressed. - Cyclomatic complexity - Code duplication - Test coverage percentage - Documentation coverage - Technical debt indicators + Cyclomatic complexity, code duplication, test coverage, doc coverage, tech debt. diff --git a/.roo/rules-docs-extractor/4_tool_usage_guide.xml b/.roo/rules-docs-extractor/4_tool_usage_guide.xml index a94fdfc0d8..d746141daa 100644 --- a/.roo/rules-docs-extractor/4_tool_usage_guide.xml +++ b/.roo/rules-docs-extractor/4_tool_usage_guide.xml @@ -1,16 +1,15 @@ - Specific guidance on using tools effectively for comprehensive documentation extraction, - with emphasis on gathering complete information across all aspects of a feature. + Guidance on using tools for documentation extraction. codebase_search - Initial discovery of feature-related code + Initial code discovery. - Finding feature entry points + Find feature entry points authentication login user session JWT token @@ -18,7 +17,7 @@ ]]> - Locating business logic + Find business logic calculate pricing discount tax invoice billing @@ -26,7 +25,7 @@ ]]> - Finding configuration + Find configuration config settings environment variables .env process.env @@ -38,11 +37,11 @@ list_code_definition_names - Understanding code structure and organization + Understand code structure. - Use on directories containing core feature logic - Analyze both implementation and test directories - Look for patterns in naming conventions + Use on core feature directories. + Analyze implementation and test directories. + Look for naming patterns. @@ -53,12 +52,12 @@ read_file - Deep analysis of specific implementations + Analyze specific implementations. - Read main feature files first - Follow imports to understand dependencies - Read test files to understand expected behavior - Examine configuration and type definition files + Read main feature files. + Follow imports to find dependencies. + Read test files for expected behavior. + Examine config and type definition files. @@ -85,10 +84,10 @@ search_files - Finding specific patterns and implementations + Find specific patterns. - Find all API endpoints + Find API endpoints src @@ -97,7 +96,7 @@ ]]> - Find error handling patterns + Find error handling src @@ -106,7 +105,7 @@ ]]> - Find configuration usage + Find config usage src @@ -120,14 +119,14 @@ - Create the final documentation file when generating new documentation from scratch. - This tool is NOT used when reviewing a user-provided document section. In that scenario, feedback is provided directly in the chat. + Create documentation file for new docs. + Not used for reviews. Feedback for reviews is provided in chat. DOCS-TEMP-[feature-name].md - Use descriptive feature names in filename - Include table of contents with anchors - Use consistent markdown formatting - Include code examples with syntax highlighting + Use descriptive feature name in filename. + Include table of contents. + Use consistent Markdown formatting. + Include syntax-highlighted code examples. @@ -149,32 +148,32 @@ The authentication system provides secure user authentication using JWT tokens.. - Clarify requirements when multiple interpretations exist + Clarify ambiguous requirements. - Multiple features with similar names exist - Documentation depth needs clarification - Target audience priorities need definition + Multiple features have similar names. + Documentation depth is unclear. + Audience priorities are undefined. -Which aspects of the authentication system should I focus on? +Which authentication aspects should be the focus? -Complete authentication flow including JWT tokens, session management, and OAuth integration -Only the JWT token implementation and validation -OAuth2 integration with external providers -Password reset and account recovery workflows +The complete flow (JWT, sessions, OAuth). +Only JWT implementation and validation. +Only OAuth2 integration. +Password reset and recovery workflows. ]]> -What level of technical detail should the documentation include? +What level of technical detail is needed? -High-level overview suitable for all audiences -Detailed technical implementation for developers -API reference with code examples -Complete coverage for all audience types +High-level overview for all audiences. +Detailed developer implementation. +API reference with code examples. +Full coverage for all audiences. ]]> @@ -183,21 +182,21 @@ The authentication system provides secure user authentication using JWT tokens.. - + - Systematic approach to finding all files related to a feature + Find all files related to a feature. - Start with semantic search + Start with semantic search. -feature implementation main logic core functionality +feature implementation main logic ]]> - List directory structure + List directory structure. src/features @@ -206,7 +205,7 @@ The authentication system provides secure user authentication using JWT tokens.. ]]> - Find related tests + Find related tests. src @@ -216,7 +215,7 @@ The authentication system provides secure user authentication using JWT tokens.. ]]> - Locate configuration files + Find config files. . @@ -230,14 +229,14 @@ The authentication system provides secure user authentication using JWT tokens.. - Follow import chains to understand all dependencies + Follow import chains to map dependencies. - Read main feature file - Extract all imports - Read each imported file - Recursively analyze their imports - Build dependency graph + Read main file. + Extract all imports. + Read each imported file. + Recursively analyze imports. + Build dependency graph. @@ -256,35 +255,31 @@ The authentication system provides secure user authentication using JWT tokens.. - Extract complete API documentation from code + Extract API documentation from code. - Route definitions - Request/response schemas - Authentication requirements - Rate limiting rules - Error responses + Route definitions, request/response schemas, auth requirements, rate limiting, error responses. - Find all route files - Extract route definitions - Find associated controllers - Analyze request validation - Document response formats + Find route files. + Extract route definitions. + Find controllers. + Analyze request validation. + Document response formats. - Use tests to understand expected behavior + Use tests to document expected behavior. - Tests show real usage examples - Test descriptions explain functionality - Edge cases are often tested - Expected outputs are documented + Tests provide usage examples. + Test descriptions explain functionality. + Tests cover edge cases. + Tests document expected outputs. @@ -354,44 +349,31 @@ config\.(\w+)\.(\w+) - - Organize output for easy navigation + + Organize output for navigation. - - Clear hierarchy with numbered sections - - Consistent heading levels - - Table of contents with links - - Cross-references between sections + - Clear hierarchy, consistent headings, ToC with links, cross-references. - Include relevant code examples + Include relevant code examples. - - Use syntax highlighting - - Show both request and response - - Include error cases - - Provide language-specific examples + - Use syntax highlighting, show request/response, include error cases. - - Suggest where diagrams would help + + Suggest diagrams where helpful. - - Architecture diagrams - - Sequence diagrams - - Data flow diagrams - - State machines + - Architecture, sequence, data flow, state machine diagrams. - - Always include important metadata + + Include important metadata. - - Version compatibility - - Last updated date - - Feature status (stable/beta/deprecated) - - Performance characteristics - - Security considerations + - Version compatibility, last updated, status, performance, security. diff --git a/.roo/rules-docs-extractor/5_complete_extraction_examples.xml b/.roo/rules-docs-extractor/5_complete_extraction_examples.xml index 6248a9587f..3975b5b262 100644 --- a/.roo/rules-docs-extractor/5_complete_extraction_examples.xml +++ b/.roo/rules-docs-extractor/5_complete_extraction_examples.xml @@ -1,48 +1,42 @@ - Complete examples demonstrating the full documentation extraction workflow - for different types of features and components. + Examples of the documentation extraction workflow. - Extract comprehensive documentation for a JWT-based authentication system - including login, logout, token refresh, and role-based access control. + Extract documentation for a JWT-based authentication system, including login, token refresh, and RBAC. - Initial feature discovery + Discover feature authentication JWT login logout token refresh auth middleware ]]> - - Auth controller files - - JWT service implementations - - Middleware functions - - User model with auth fields - - Auth route definitions + - Auth controllers, services, middleware, models, and routes. - Analyze authentication structure + Analyze structure src/auth ]]> - - Identify main classes and functions - - Map authentication flow - - Find token generation/validation logic + - Identify main classes/functions. + - Map auth flow. + - Find token generation/validation logic. - Read core implementation files + Read core files @@ -75,16 +69,12 @@ ]]> - - POST /auth/login - - POST /auth/logout - - POST /auth/refresh - - GET /auth/profile - - POST /auth/register + - POST /auth/login, POST /auth/logout, POST /auth/refresh, GET /auth/profile, POST /auth/register - Document configuration + Extract configuration src @@ -94,7 +84,7 @@ - Analyze security measures + Analyze security src/auth @@ -104,7 +94,7 @@ - Generate documentation + Generate docs DOCS-TEMP-authentication-system.md @@ -552,24 +542,23 @@ DEBUG=auth:* npm start - Start with semantic search to find all related files - Read multiple files together for context - Extract API documentation from route definitions - Use tests to understand expected behavior - Document security measures comprehensively - Include troubleshooting based on common errors + Use semantic search to find related files. + Read multiple files for context. + Extract API docs from route definitions. + Use tests to understand behavior. + Document security measures. + Include troubleshooting for common errors. - Extract documentation for database models, relationships, migrations, - and data access patterns. + Extract documentation for database models, relationships, and migrations. - Find database-related files + Find DB files database schema model entity migration table column relationship @@ -578,7 +567,7 @@ DEBUG=auth:* npm start - Analyze model definitions + Analyze models src/models diff --git a/.roo/rules-docs-extractor/6_communication_guidelines.xml b/.roo/rules-docs-extractor/6_communication_guidelines.xml index aed30f4094..908b1fcfb6 100644 --- a/.roo/rules-docs-extractor/6_communication_guidelines.xml +++ b/.roo/rules-docs-extractor/6_communication_guidelines.xml @@ -1,90 +1,87 @@ - Guidelines for communicating with users and formatting documentation output - during the extraction process. + Guidelines for user communication and output formatting. - - Users will specify what they want documented in their initial message - Start working immediately based on their request - Only ask for clarification if genuinely ambiguous - + + Act on the user's request immediately. + Only ask for clarification if the request is ambiguous. + - + - Multiple features with identical names found - Request is genuinely ambiguous (rare) - User explicitly asks for options + Multiple features with similar names are found. + The request is ambiguous. + The user explicitly asks for options. -I found multiple authentication systems. Which one should I document? +Found multiple auth systems. Which to document? -JWT-based authentication system (src/auth/jwt/*) +JWT-based system (src/auth/jwt/*) OAuth2 integration (src/auth/oauth/*) -Basic authentication middleware (src/middleware/basic-auth.ts) -All authentication features comprehensively +Basic auth middleware (src/middleware/basic-auth.ts) +All of them ]]> - + - Starting major analysis phase - Completed significant extraction - Found unexpected complexity - Discovered related features + Starting a major analysis phase. + Extraction is complete. + Unexpected complexity is found. - + - Alert user to potential security concerns found during analysis + Alert user to security concerns found during analysis. - Note deprecated features that need migration documentation + Note deprecated features needing migration docs. - - Highlight areas where code lacks inline documentation + + Highlight code that lacks inline documentation. - Warn about intricate dependency chains affecting the feature + Warn about complex dependency chains. - + @@ -92,18 +89,14 @@ This feedback can be copied and pasted for your documentation team. - - Use # for main title only - Use ## for major sections - Use ### for subsections - Use #### sparingly for minor subsections - Never skip heading levels - + + Use # for main title, ## for major sections, ### for subsections. + Never skip heading levels. + - Always specify language for syntax highlighting - Use appropriate language identifiers (typescript, javascript, json, yaml, bash) - Include file paths as comments when relevant + Always specify language for syntax highlighting (e.g., typescript, json, bash). + Include file paths as comments where relevant. - Use tables for structured data like configurations - Include headers with proper alignment - Keep cell content concise + Use tables for structured data like configs. + Include headers and align columns. + Keep cell content brief. - Use bullet points for unordered lists - Use numbers for sequential steps - Nest lists with proper indentation - Keep list items parallel in structure + Use bullets for unordered lists, numbers for sequential steps. + Keep list items parallel in structure. [Link text](#section-anchor) - Use lowercase, hyphenated anchors - Test all internal links + Use lowercase, hyphenated anchors. Test all links. [Link text](https://example.com) - Use HTTPS when available - Link to official documentation + Use HTTPS. Link to official docs. `path/to/file.ts` - Use relative paths from project root - Use backticks for inline file references + Use relative paths from project root, in backticks. @@ -160,15 +148,15 @@ export class AuthService { > ⚠️ **Warning**: [message] - Security concerns, breaking changes, deprecations + Security, breaking changes, deprecations. > 📝 **Note**: [message] - Important information, clarifications + Important info, clarifications. > 💡 **Tip**: [message] - Best practices, optimization suggestions + Best practices, optimizations. @@ -186,138 +174,110 @@ Status: Stable - - Be conversational and approachable - Use active voice and "you" to address the reader - Lead with benefits, not features - Use concrete examples and scenarios - Keep paragraphs short and scannable - Avoid unnecessary technical details - + + Be direct, not conversational. + Use active voice. + Lead with benefits. + Use concrete examples. + Keep paragraphs short. + Avoid unnecessary technical details. + - - Write as if explaining to a colleague who isn't technical - Use analogies and comparisons to familiar concepts - Focus on "what" and "why" before "how" - Include practical examples users can relate to - Address common concerns and questions directly - - - - - Friendly, helpful, encouraging - Plain language, minimal jargon - Real-world scenarios, before/after comparisons - Problem → Solution → Benefits → How to use + + + Technical and direct. + Standard programming terms. + Code snippets, implementation details. - - - Technical when needed, but still approachable - Use standard programming terminology - Include code snippets and implementation details + + Instructional, step-by-step. + Simple language, no jargon. + Screenshots, real-world scenarios. - - - Friendly, instructional, step-by-step - Avoid technical jargon, explain concepts simply - Use screenshots and real-world scenarios + + Operational focus. + IT/DevOps terms. + CLI examples, configs. - - - Professional, operational focus - Use IT/DevOps terminology - Include command-line examples and configurations - - - - Business-oriented, value-focused - Use business terminology, avoid implementation details - Include metrics, ROI, and business benefits - - + - Summary of what was documented - Key findings or insights - File location and name - Suggestions for next steps (if applicable) + Summary of documented feature. + Key findings. + File location. + Next step suggestions (if applicable). - + - I couldn't find a feature matching "[feature name]". Here are some similar features I found: + Could not find a feature matching "[feature name]". Similar features found: - [List similar features] - Would you like me to document one of these instead? + Document one of these instead? - + - The code for [feature] has limited inline documentation. I'll extract what I can from: - - Code structure and naming - - Test files - - Related documentation - - Usage patterns + Code for [feature] has limited inline documentation. Extracting from code structure, tests, and usage patterns. - This feature is quite complex with [X] components. Would you like me to: - - Document everything comprehensively (may result in a large document) - - Focus on the core functionality - - Split into multiple documentation files + This feature is complex. Choose documentation scope: + - Document comprehensively + - Focus on core functionality + - Split into multiple documents - + - All sections have content (no placeholders) - Code examples are syntactically correct - Links and cross-references work - Tables are properly formatted - Version information is included - File naming follows convention + No placeholder content remains. + Code examples are correct. + Links and cross-references work. + Tables are formatted correctly. + Version info is included. + Filename follows conventions. \ No newline at end of file diff --git a/.roo/rules-docs-extractor/7_user_friendly_examples.xml b/.roo/rules-docs-extractor/7_user_friendly_examples.xml index 9de359a62a..6b94e88de6 100644 --- a/.roo/rules-docs-extractor/7_user_friendly_examples.xml +++ b/.roo/rules-docs-extractor/7_user_friendly_examples.xml @@ -1,93 +1,87 @@ - Examples and patterns for creating documentation that prioritizes user experience - and practical understanding over technical completeness. + Examples for creating user-focused, practical documentation. - - The concurrent file read feature uses parallel processing to read multiple files. - Read multiple files at once, saving time and reducing interruptions. + + The concurrent file read feature uses parallel processing. + Read multiple files at once, reducing interruptions. - This feature improves efficiency. - Instead of approving 10 file reads one by one, approve them all at once and get your answer faster. + This improves efficiency. + Instead of approving 10 file reads one-by-one, approve them all at once. - - The feature uses a thread pool with configurable concurrency limits to process file I/O operations. - Roo can read up to 100 files at once (you can change this limit in settings). + + The feature uses a thread pool with configurable concurrency limits. + Roo reads up to 100 files at once (changeable in settings). - + Users must configure the concurrent file read limit parameter. - You can adjust how many files Roo reads at once in the settings. + Adjust how many files Roo reads at once in settings. - + - + - + - + @@ -95,160 +89,130 @@ You can customize this feature in Roo's settings: - - - - - + + The system imposes a hard limit of 100 concurrent operations. - Roo can handle up to 100 files at once - more than enough for most projects! + Roo handles up to 100 files at once. - + Error: Maximum concurrency threshold exceeded. - Oops! That's too many files at once. Try lowering the file limit in settings. + Too many files requested. Lower the file limit in settings. - + Reduces API call overhead through request batching. - Get answers faster by reading all the files Roo needs in one go. + Get answers faster by reading all needed files at once. - + - - - Error messages: ⚠️ - Tips: 💡 - Important notes: 📝 + + + Error: ⚠️ + Tip: 💡 + Note: 📝 Security: 🔒 - + - - For emphasis on key points - For settings names, file paths, or commands - For important callouts or warnings - - + + For emphasis + For settings, file paths, or commands + For callouts or warnings + + - Concurrent File Reads Documentation + Concurrent File Reads Doc - Does it start with benefits, not features? - Are technical terms explained or avoided? - Does it use "you" to address the reader? - Are there practical examples or scenarios? - Is the tone conversational and friendly? + Does it start with benefits? + Are technical terms avoided? + Is the tone direct? + Are there practical examples? Are sections short and scannable? - Does it answer common user questions? - Is help easily accessible? + Does it answer user questions? + Is help accessible? \ No newline at end of file