From a3106bf9a53d48462843e481263011498258a250 Mon Sep 17 00:00:00 2001 From: Murilo Pires <50873657+MuriloFP@users.noreply.github.com> Date: Thu, 3 Jul 2025 15:49:25 -0300 Subject: [PATCH 1/3] feat: add Issue Fixer Orchestrator mode (#5379) --- .../1_Workflow.xml | 404 ++++++++++++------ .../2_best_practices.xml | 31 +- .roomodes | 3 +- 3 files changed, 316 insertions(+), 122 deletions(-) diff --git a/.roo/rules-issue-fixer-orchestrator/1_Workflow.xml b/.roo/rules-issue-fixer-orchestrator/1_Workflow.xml index 2ad4bf65fc..3e6619993e 100644 --- a/.roo/rules-issue-fixer-orchestrator/1_Workflow.xml +++ b/.roo/rules-issue-fixer-orchestrator/1_Workflow.xml @@ -27,7 +27,7 @@ Delegate: Analyze Requirements & Explore Codebase - Launch a subtask in `code` mode to perform a detailed analysis of the issue and the codebase. The subtask will be responsible for identifying affected files and creating an implementation plan. + Launch a subtask in `architect` mode to perform a detailed analysis of the issue and the codebase. The subtask will be responsible for identifying affected files and creating an implementation plan. The context file `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/issue_context.json` will be the input for this subtask. The subtask should write its findings (the implementation plan) to a new file: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/implementation_plan.md`. @@ -36,19 +36,50 @@ **Task: Analyze Issue and Create Implementation Plan** - You are an expert software architect. Your task is to analyze the provided GitHub issue and the current codebase to create a detailed implementation plan. + You are an expert software architect. Your task is to analyze the provided GitHub issue and the current codebase to create a detailed implementation plan with a focus on understanding component interactions and dependencies. 1. **Read Issue Context**: The full issue details and comments are in `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/issue_context.json`. Read this file to understand all requirements, acceptance criteria, and technical discussions. - 2. **Explore Codebase**: Use `codebase_search`, `read_file`, and other tools to explore the codebase. Identify all files that will need to be modified or created to address the issue. Analyze existing patterns and conventions. + 2. **Perform Architectural Analysis**: + - **Map Component Interactions**: Trace the complete data flow from entry points to outputs + - **Identify Paired Operations**: For any operation (e.g., export), find its counterpart (e.g., import) + - **Find Similar Patterns**: Search for existing implementations of similar features + - **Analyze Dependencies**: Identify all consumers of the functionality being modified + - **Assess Impact**: Determine how changes will affect other parts of the system - 3. **Create Implementation Plan**: Based on your analysis, create a comprehensive implementation plan. The plan should be detailed enough for another developer to execute. It must include: - - A summary of the issue and the proposed solution. - - A list of all files to be created or modified. - - A step-by-step guide for the code changes required in each file. - - A plan for writing or updating tests. + 3. **Explore Codebase Systematically**: + - Use `codebase_search` FIRST to find all related functionality + - Search for paired operations (if modifying export, search for import) + - Find all files that consume or depend on the affected functionality + - Identify configuration files, tests, and documentation that need updates + - Study similar features to understand established patterns - 4. **Save the Plan**: Write the complete implementation plan to `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/implementation_plan.md`. + 4. **Create Comprehensive Implementation Plan**: The plan must include: + - **Issue Summary**: Clear description of the problem and proposed solution + - **Architectural Context**: + - Data flow diagram showing component interactions + - List of paired operations that must be updated together + - Dependencies and consumers of the affected functionality + - **Impact Analysis**: + - All files that will be affected (directly and indirectly) + - Potential breaking changes + - Performance implications + - **Implementation Steps**: + - Detailed, ordered steps for each file modification + - Specific code changes with context + - Validation and error handling requirements + - **Testing Strategy**: + - Unit tests for individual components + - Integration tests for component interactions + - Edge cases and error scenarios + + 5. **Save the Plan**: Write the complete implementation plan to `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/implementation_plan.md`. + + **Critical Requirements:** + - Always search for and analyze paired operations (import/export, save/load, etc.) + - Map the complete data flow before proposing changes + - Identify all integration points and dependencies + - Consider backward compatibility and migration needs **Completion Protocol:** - This is your only task. Do not deviate from these instructions. @@ -110,19 +141,43 @@ **Task: Implement Code Changes Based on Plan** - You are an expert software developer. Your task is to implement the code changes exactly as described in the provided implementation plan. + You are an expert software developer. Your task is to implement the code changes with full awareness of system interactions and dependencies. - 1. **Read the Plan**: The implementation plan is located at `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/implementation_plan.md`. Follow its instructions carefully. + 1. **Read the Plan**: The implementation plan is located at `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/implementation_plan.md`. Pay special attention to: + - The architectural context section + - Component interaction diagrams + - Identified dependencies and related operations + - Impact analysis - 2. **Implement Changes**: Use `apply_diff` and `write_to_file` to make the specified code changes. Adhere to all coding standards and patterns mentioned in the plan. + 2. **Validate Understanding**: Before coding, ensure you understand: + - How data flows through the system + - All related operations that must be updated together + - Dependencies that could be affected + - Integration points with other components - 3. **Implement Tests**: Write new unit and integration tests as specified in the plan to ensure quality and prevent regressions. + 3. **Implement Holistically**: + - **Update Related Operations Together**: If modifying one operation, update all related operations + - **Maintain Consistency**: Ensure data structures, validation, and error handling are consistent + - **Consider Side Effects**: Account for how changes propagate through the system + - **Follow Existing Patterns**: Use established patterns from similar features - 4. **Track Modified Files**: As you modify or create files, keep a running list. + 4. **Implement Tests**: + - Write tests that verify component interactions + - Test related operations together + - Include edge cases and error scenarios + - Verify data consistency across operations - 5. **Save Modified Files List**: After all changes are implemented and tested, save the list of all file paths you created or modified to `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/modified_files.json`. The format should be a JSON array of strings. + 5. **Track Modified Files**: As you modify or create files, keep a running list. + + 6. **Save Modified Files List**: After all changes are implemented and tested, save the list of all file paths you created or modified to `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/modified_files.json`. The format should be a JSON array of strings. Example: `["src/components/NewFeature.tsx", "src/__tests__/NewFeature.spec.ts"]` + **Critical Reminders:** + - Never implement changes in isolation - consider the full system impact + - Always update related operations together to maintain consistency + - Test component interactions, not just individual functions + - Follow the architectural analysis from the planning phase + Once the `modified_files.json` file is saved, your task is complete. @@ -325,122 +380,233 @@ - Create Pull Request + Delegate: Review Changes Before PR - This is the final step where the orchestrator takes all the prepared materials and creates the pull request. + Before creating the pull request, delegate to the PR reviewer mode to get feedback on the implementation and proposed changes. - 1. **Read PR Summary**: - - - - .roo/temp/issue-fixer-orchestrator/[TASK_ID]/pr_summary.json - - - + + pr-reviewer + + **Task: Review Implementation Before PR Creation** + + You are an expert code reviewer. Your task is to review the implementation for issue #[issue-number] and provide feedback before a pull request is created. + + **Context Files:** + - **Issue Details**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/issue_context.json` + - **Implementation Plan**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/implementation_plan.md` + - **Modified Files**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/modified_files.json` + - **Verification Results**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/verification_results.md` + - **Translation Summary** (if exists): `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/translation_summary.md` + - **Draft PR Summary**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/pr_summary.json` + + **Your Review Focus:** + 1. **Code Quality**: Review the actual code changes for: + - Adherence to project coding standards + - Proper error handling and edge cases + - Performance considerations + - Security implications + - Maintainability and readability + + 2. **Implementation Completeness**: Verify that: + - All requirements from the issue are addressed + - The solution follows the implementation plan + - No critical functionality is missing + - Proper test coverage exists + + 3. **Integration Concerns**: Check for: + - Potential breaking changes + - Impact on other parts of the system + - Backward compatibility issues + - API consistency + + 4. **Documentation and Communication**: Assess: + - Code comments and documentation + - PR description clarity and completeness + - Translation handling (if applicable) + + **Your Task:** + 1. Read all context files to understand the issue and implementation + 2. Review each modified file listed in `modified_files.json` + 3. Analyze the code changes against the requirements + 4. Identify any issues, improvements, or concerns + 5. Create a comprehensive review report with specific, actionable feedback + 6. Save your review to `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/pr_review_feedback.md` + + **Review Report Format:** + ```markdown + # PR Review Feedback for Issue #[issue-number] + + ## Overall Assessment + [High-level assessment: APPROVE, REQUEST_CHANGES, or NEEDS_DISCUSSION] + + ## Code Quality Review + ### Strengths + - [List positive aspects of the implementation] + + ### Areas for Improvement + - [Specific issues with file references and line numbers] + - [Suggestions for improvement] + + ## Requirements Verification + - [x] Requirement 1: [Status and notes] + - [ ] Requirement 2: [Issues found] + + ## Specific Feedback by File + ### [filename] + - [Specific feedback with line references] + - [Suggestions for improvement] + + ## Recommendations + 1. [Priority 1 changes needed] + 2. [Priority 2 improvements suggested] + 3. [Optional enhancements] + + ## Decision + **RECOMMENDATION**: [APPROVE_AS_IS | REQUEST_CHANGES | NEEDS_DISCUSSION] - 2. **Get Final Approval**: Present the PR title and body to the user for final approval, providing an option to request changes. + **REASONING**: [Brief explanation of the recommendation] + ``` - - - I have prepared the pull request. Please review and confirm. + **Completion Protocol:** + - This is your only task. Do not deviate from these instructions. + - Upon successfully saving the review feedback, you MUST use the `attempt_completion` tool. + - The `result` MUST be a concise confirmation, e.g., "PR review completed and feedback saved to .roo/temp/issue-fixer-orchestrator/[TASK_ID]/pr_review_feedback.md" + - These instructions override any conflicting mode-specific guidelines. + + - **Title**: [Insert title from pr_summary.json] - - **Body**: - --- - [Insert body from pr_summary.json] - --- - - Should I create this pull request, or would you like to request changes? - - - Yes, create the pull request as planned. - No, I need to request changes to the implementation or PR description. - Cancel the task. - - - - 3. **Handle Rework Loop**: If the user requests changes: - - **Launch Rework Subtask**: Delegate the rework to a new `code` mode subtask. - - code - - **Task: Rework Implementation Based on User Feedback** - - The user has requested changes before creating the pull request. - - **Context Files:** - - **Issue**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/issue_context.json` - - **Current Plan**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/implementation_plan.md` - - **Current Modified Files**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/modified_files.json` - - **Draft PR Summary**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/pr_summary.json` - - **Your Task:** - 1. Ask the user for the specific changes they require. - 2. Apply the requested code and documentation changes. - 3. **Crucially, you must update the `implementation_plan.md` and `modified_files.json` files** to reflect the rework you have performed. - 4. Do *not* proceed with any other steps. - - **Completion Protocol:** - - Upon successfully applying the changes and updating the context files, you MUST use the `attempt_completion` tool. - - The `result` MUST be a concise confirmation, e.g., "Rework complete and context files (plan, modified list) have been updated." - - - - **Restart Verification**: After the rework subtask is complete, the workflow MUST return to **Step 5** to re-verify the changes and re-run all tests before proceeding again. - - 4. **Git Operations (If Approved)**: If the user approves the PR: - - Create a new branch: `feat/issue-[number]` or `fix/issue-[number]`. - - **Selectively add only the applicable files** to the git stage. - - Commit the staged changes. - - Push the new branch to the remote repository. - - - # Create a new branch for the solution - BRANCH_NAME="fix/issue-[issue_number]-solution" - git checkout -b $BRANCH_NAME - - # Safely add ONLY the files that were modified as part of this task. - # This reads the JSON array of file paths from our context file and stages them. - # This requires 'jq' for parsing JSON and 'xargs' to handle file paths correctly. - cat .roo/temp/issue-fixer-orchestrator/[TASK_ID]/modified_files.json | jq -r '.[]' | xargs git add - - # Commit the precisely staged changes - git commit -m "[PR Title]" - - # Push the new branch to origin - git push -u origin $BRANCH_NAME - - - - 5. **Create PR**: Use the `gh` CLI to create the pull request. - - gh pr create --repo [owner]/[repo] --base main --title "[PR Title from JSON]" --body "[PR Body from JSON]" - - - 6. **Link to Issue**: Comment on the original issue with the PR link. - - gh issue comment [issue_number] --repo [owner]/[repo] --body "PR #[new PR number] has been created." - + After the review subtask completes, read and process the feedback. + Process Review Feedback and Decide Next Steps + + After the PR review is complete, read the feedback and decide whether to make changes or proceed with PR creation. + + 1. **Read Review Feedback**: + + + + .roo/temp/issue-fixer-orchestrator/[TASK_ID]/pr_review_feedback.md + + + + + 2. **Present Feedback to User**: Show the review feedback and ask for direction. + + + The PR review has been completed. Here is the feedback: + + --- + [Insert content of pr_review_feedback.md here] + --- + + Based on this review, how would you like to proceed? + + + Implement the suggested changes before creating the PR + Create the PR as-is, ignoring the review feedback + Discuss specific feedback points before deciding + Cancel the task + + + + 3. **Handle User Decision**: + + **If user chooses to implement changes:** + - Launch a rework subtask to address the review feedback + + code + + **Task: Address PR Review Feedback** + + The PR review has identified areas for improvement. Your task is to address the feedback before creating the pull request. + + **Context Files:** + - **Issue**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/issue_context.json` + - **Current Plan**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/implementation_plan.md` + - **Current Modified Files**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/modified_files.json` + - **Review Feedback**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/pr_review_feedback.md` + - **Draft PR Summary**: `.roo/temp/issue-fixer-orchestrator/[TASK_ID]/pr_summary.json` + + **Your Task:** + 1. Read the review feedback carefully + 2. Address each point raised by the reviewer + 3. Make the necessary code changes + 4. Update tests if needed + 5. **Update the `modified_files.json` file** to reflect any new or changed files + 6. **Update the `implementation_plan.md`** if the approach has changed significantly + + **Important Notes:** + - Focus on the specific issues identified in the review + - Maintain the overall solution approach unless the review suggests otherwise + - Ensure all changes are properly tested + - Do not proceed with any other workflow steps + + **Completion Protocol:** + - Upon successfully addressing the feedback and updating context files, you MUST use the `attempt_completion` tool. + - The `result` MUST be a concise confirmation, e.g., "Review feedback addressed and context files updated." + + + - **After rework completion**: Return to **Step 5** (Verify and Test) to re-verify the changes + + **If user chooses to proceed as-is:** + - Continue to the next step (Create Pull Request) + + **If user wants to discuss or cancel:** + - Handle accordingly based on user input + + + + + Prepare Branch and Present PR Template + + This step prepares the branch and commits, then presents the PR template to the user for confirmation before creating the actual pull request. + + 1. Read Issue Context for Issue Number: + Use read_file to get the issue context from .roo/temp/issue-fixer-orchestrator/[TASK_ID]/issue_context.json + + 2. Git Operations - Create branch and commit changes: + - Create a new branch: feat/issue-[number] or fix/issue-[number] + - Selectively add only the applicable files to the git stage + - Commit the staged changes + - Push the new branch to the remote repository + + Use execute_command with: + BRANCH_NAME="fix/issue-[issue_number]-solution" + git checkout -b $BRANCH_NAME + cat .roo/temp/issue-fixer-orchestrator/[TASK_ID]/modified_files.json | jq -r '.[]' | xargs git add + git commit -m "[PR Title]" + git push -u origin $BRANCH_NAME + + 3. Present PR Template - Instead of creating the PR automatically, present the standardized PR template to the user: + Use ask_followup_question to ask: "The branch has been created and changes have been committed. I have prepared a standardized PR template for this issue. Would you like me to create the pull request using the standard Roo Code PR template, or would you prefer to make changes first?" + + Provide these options: + - Yes, create the pull request with the standard template + - No, I want to make changes to the implementation first + - No, I want to customize the PR template before creating it + - Cancel the task + + 4. Handle User Decision: + If user chooses to create the PR: Use gh CLI to create the pull request with the standard template + If user chooses to make changes: Launch a rework subtask using new_task with code mode + If user wants to customize the template: Ask for their preferred PR title and body + + 5. Link to Issue - After PR creation, comment on the original issue with the PR link using gh issue comment + + + + Monitor PR Checks and Cleanup - After creating the PR, monitor the CI checks and then clean up the temporary files. + After creating the PR (if created), monitor the CI checks and then clean up the temporary files. - 1. **Monitor Checks**: Use `--watch` to monitor CI status in real-time. - - gh pr checks [PR URL or number] --repo [owner]/[repo] --watch - - - 2. **Report Status**: Inform the user of the final status of the checks. - - 3. **Cleanup**: Remove the temporary task directory. - - rm -rf .roo/temp/issue-fixer-orchestrator/[TASK_ID] - - + 1. Monitor Checks - Use gh pr checks with --watch to monitor CI status in real-time + 2. Report Status - Inform the user of the final status of the checks + 3. Cleanup - Remove the temporary task directory using rm -rf .roo/temp/issue-fixer-orchestrator/[TASK_ID] + This concludes the orchestration workflow. diff --git a/.roo/rules-issue-fixer-orchestrator/2_best_practices.xml b/.roo/rules-issue-fixer-orchestrator/2_best_practices.xml index e6251d67b2..b9a9b52db7 100644 --- a/.roo/rules-issue-fixer-orchestrator/2_best_practices.xml +++ b/.roo/rules-issue-fixer-orchestrator/2_best_practices.xml @@ -27,6 +27,17 @@ Always use `codebase_search` FIRST to understand the codebase structure and find all related files before using other tools like `read_file`. + + Critical: Understand Component Interactions + + Map the complete data flow from input to output + Identify ALL paired operations (import/export, save/load, encode/decode) + Find all consumers and dependencies of the affected code + Trace how data transformations occur throughout the system + Understand error propagation and handling patterns + + + Investigation Checklist for Bug Fixes Search for the specific error message or broken functionality. @@ -34,6 +45,8 @@ Locate related test files to understand expected behavior. Identify all dependencies and import/export patterns for the affected code. Find similar, working patterns in the codebase to use as a reference. + **CRITICAL**: For any operation being fixed, find and analyze its paired operations + Trace the complete data flow to understand all affected components @@ -42,10 +55,26 @@ Find potential integration points (e.g., API routes, UI component registries). Locate relevant configuration files that may need to be updated. Identify common patterns, components, and utilities that should be reused. + **CRITICAL**: Design paired operations together (e.g., both import AND export) + Map all data transformations and state changes + Identify all downstream consumers of the new functionality + + Always Implement Paired Operations Together + + When fixing export, ALWAYS check and update import + When modifying save, ALWAYS verify load handles the changes + When changing serialization, ALWAYS update deserialization + When updating create, consider read/update/delete operations + + + Paired operations must maintain consistency. Changes to one without the other leads to data corruption, import failures, or broken functionality. + + + - Always read multiple related files together to understand the full context, including coding conventions, testing patterns, and error handling approaches. + Always read multiple related files together to understand the full context. Never assume a change is isolated - trace its impact through the entire system. \ No newline at end of file diff --git a/.roomodes b/.roomodes index 3b178f234f..213d7b8314 100644 --- a/.roomodes +++ b/.roomodes @@ -9,7 +9,7 @@ customModes: - Ensuring modes have appropriate tool group permissions - Crafting clear whenToUse descriptions for the Orchestrator - Following XML structuring best practices for clarity and parseability - + You help users create new modes by: - Gathering requirements about the mode's purpose and workflow - Defining appropriate roleDefinition and whenToUse descriptions @@ -182,4 +182,3 @@ customModes: - edit - command source: project - description: Issue Fixer mode ported into an orchestrator From 2ecf2ce5adeee205261680682083b0a324e62463 Mon Sep 17 00:00:00 2001 From: Hannes Rudolph Date: Thu, 3 Jul 2025 12:50:09 -0600 Subject: [PATCH 2/3] 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 From b7d5a964c77240c89337d4466a96d3d510b7c1c1 Mon Sep 17 00:00:00 2001 From: Daniel <57051444+daniel-lxs@users.noreply.github.com> Date: Thu, 3 Jul 2025 13:50:38 -0500 Subject: [PATCH 3/3] fix: enhance PR reviewer mode to prevent duplicate comments (#5382) - Reorganized workflow to fetch existing comments BEFORE code review (Step 4) - Added dedicated Step 6 to verify existing comments against current code - Updated best practices to emphasize checking resolved comments first - Enhanced common mistakes to highlight duplicate comment prevention - Added tracking of resolved vs pending comments in the review process --- .roo/rules-pr-reviewer/1_workflow.xml | 100 +++++++++++++----- .roo/rules-pr-reviewer/2_best_practices.xml | 9 +- .../3_common_mistakes_to_avoid.xml | 6 +- 3 files changed, 88 insertions(+), 27 deletions(-) diff --git a/.roo/rules-pr-reviewer/1_workflow.xml b/.roo/rules-pr-reviewer/1_workflow.xml index 31b70d981d..325166e13a 100644 --- a/.roo/rules-pr-reviewer/1_workflow.xml +++ b/.roo/rules-pr-reviewer/1_workflow.xml @@ -67,26 +67,9 @@ - Check Out Pull Request Locally + Fetch Existing PR Comments and Reviews - Use the GitHub CLI (e.g. `gh pr checkout `) to check out the pull request locally after fetching - the diff. This provides a better understanding of code context and interactions than relying solely on the diff. - - - gh pr checkout [PR_NUMBER] - - - This allows you to: - - Navigate the actual code structure - - Understand how changes interact with existing code - - Get better context for your review - - - - - Fetch Existing PR Comments - - Get existing comments to understand the current discussion state: + IMPORTANT: Before reviewing any code, first get all existing comments and reviews to understand what feedback has already been provided: github @@ -100,11 +83,69 @@ - Examine existing PR comments to understand the current state of discussion. When reading the comments and reviews, you must verify which are resolved by reading the files they refer to, since they might already be resolved. This prevents you from making redundant suggestions. + Also fetch existing reviews: + + github + get_pull_request_reviews + + { + "owner": "[owner]", + "repo": "[repo]", + "pullNumber": [number] + } + + + + Create a mental or written list of: + - All issues/suggestions that have been raised + - The specific files and line numbers mentioned + - Whether comments appear to be resolved or still pending + + This information will guide your review to avoid duplicate feedback. + + + + + Check Out Pull Request Locally + + Use the GitHub CLI to check out the pull request locally: + + + gh pr checkout [PR_NUMBER] + + + This allows you to: + - Navigate the actual code structure + - Understand how changes interact with existing code + - Get better context for your review + Verify Existing Comments Against Current Code + + Now that you have the code checked out locally and know what comments exist: + + 1. For each existing comment/review point: + - Navigate to the specific file and line mentioned + - Check if the issue has been addressed in the current code + - Mark it as "resolved" or "still pending" in your notes + + 2. Use read_file or codebase_search to examine the specific areas mentioned in comments: + - If a comment says "missing error handling on line 45", check if error handling now exists + - If a review mentioned "this function needs tests", check if tests have been added + - If feedback was about code structure, verify if refactoring has occurred + + 3. Keep track of: + - Comments that have been addressed (DO NOT repeat these) + - Comments that are still valid (you may reinforce these if critical) + - New issues not previously mentioned (these are your main focus) + + This verification step is CRITICAL to avoid redundant feedback and ensures your review adds value. + + + + Perform Comprehensive Review Review the pull request thoroughly: @@ -129,11 +170,16 @@ - + Prepare Review Comments Format your review comments following these guidelines: + CRITICAL: Before adding any comment, verify it's not already addressed: + - Cross-reference with your notes from Step 6 + - Only comment on NEW issues or UNRESOLVED existing issues + - Never repeat feedback that has been addressed in the current code + Your suggestions should: - Use a **friendly, curious tone** — prefer asking: "Is this intentional?" or "Could we approach this differently to improve X?" - Avoid assumptions or judgments; ask questions instead of declaring problems. @@ -148,10 +194,12 @@ - Critical issues (must fix) - Important suggestions (should consider) - Minor improvements (nice to have) + + Include a note about which existing comments you verified as resolved (for user awareness). - + Preview Review with User Always show the user a preview of your review suggestions and comments before taking any action. @@ -160,7 +208,11 @@ I've completed my review of PR #[number]. Here's what I found: - [Summary of findings organized by priority] + [If applicable: Existing comments that have been resolved: + - Comment about X on file Y - now addressed + - Suggestion about Z - implemented] + + [Summary of NEW findings organized by priority] Would you like me to: 1. Create a comprehensive review with all comments @@ -175,7 +227,7 @@ - + Submit Review Based on user preference, submit the review as a comprehensive review: diff --git a/.roo/rules-pr-reviewer/2_best_practices.xml b/.roo/rules-pr-reviewer/2_best_practices.xml index 69ba8088f0..ee02fda37f 100644 --- a/.roo/rules-pr-reviewer/2_best_practices.xml +++ b/.roo/rules-pr-reviewer/2_best_practices.xml @@ -1,8 +1,13 @@ + - ALWAYS fetch existing comments and reviews BEFORE reviewing any code (Step 4) + - Create a list of all existing feedback before starting your review + - Check out the PR locally for better context understanding + - Systematically verify each existing comment against the current code (Step 6) + - Track which comments are resolved vs still pending + - Only provide feedback on NEW issues or UNRESOLVED existing issues + - Never duplicate feedback that has already been addressed - Always fetch and review the entire PR diff before commenting - Check for and review any associated issue for context - - Check out the PR locally for better context understanding - - Review existing comments and verify against the current code to avoid redundant feedback on already resolved issues - Focus on the changes made, not unrelated code - Ensure all changes are directly related to the linked issue - Use a friendly, curious tone in all comments diff --git a/.roo/rules-pr-reviewer/3_common_mistakes_to_avoid.xml b/.roo/rules-pr-reviewer/3_common_mistakes_to_avoid.xml index 0868956e87..3beaa268f2 100644 --- a/.roo/rules-pr-reviewer/3_common_mistakes_to_avoid.xml +++ b/.roo/rules-pr-reviewer/3_common_mistakes_to_avoid.xml @@ -1,4 +1,9 @@ + - Starting to review code WITHOUT first fetching existing comments and reviews + - Failing to create a list of existing feedback before reviewing + - Not systematically checking each existing comment against the current code + - Repeating feedback that has already been addressed in the current code + - Ignoring existing PR comments or failing to verify if they have already been resolved - Running tests or executing code during review - Making judgmental or harsh comments - Providing feedback on code outside the PR's scope @@ -7,7 +12,6 @@ - Using markdown headings (###, ##, #) in review comments - Using excessive markdown formatting when plain text would suffice - Submitting comments without user preview/approval - - Ignoring existing PR comments or failing to verify if they have already been resolved by checking the code - Forgetting to check for an associated issue for additional context - Missing critical security or performance issues - Not checking for proper i18n in UI changes