Update issue writer rules and workflow configurations

.roo/rules-issue-writer/3_best_practices.xml

@@ -1,38 +1,172 @@
 <best_practices>
+  <mode_behavior>
+    - CRITICAL: This mode assumes the user's FIRST message is already an issue description
+    - Do NOT ask "What would you like to do?" or "Do you want to create an issue?"
+    - Immediately start the issue creation workflow when the user begins talking
+    - Treat their initial message as the problem/feature description
+    - Begin with repository detection and codebase discovery right away
+    - The user is already in "issue creation mode" by choosing this mode
+  </mode_behavior>
+
+  <template_usage>
+    - ALWAYS check for repository-specific issue templates before creating issues
+    - Use templates from .github/ISSUE_TEMPLATE/ directory if they exist
+    - Parse both YAML (.yml/.yaml) and Markdown (.md) template formats
+    - If multiple templates exist, let the user choose the appropriate one
+    - If no templates exist, create a simple generic template on the fly
+    - NEVER fall back to hardcoded templates - always use repo templates or generate minimal ones
+    - Respect template metadata like labels, assignees, and title patterns
+    - Fill templates intelligently using gathered information from codebase exploration
+  </template_usage>
+
   <problem_reporting_focus>
     - Focus on helping users describe problems clearly, not solutions
-    - The Roo team will design solutions unless the user explicitly wants to contribute
+    - The project team will design solutions unless the user explicitly wants to contribute
     - Don't push users to provide technical details they may not have
     - Make it easy for non-technical users to report issues effectively
+
+    CRITICAL: Lead with user impact:
+    - Always explain WHO is affected and WHEN the problem occurs
+    - Use concrete examples with actual values, not abstractions
+    - Show before/after scenarios with specific data
+    - Example: "Users trying to [action] see [actual result] instead of [expected result]"
   </problem_reporting_focus>
 
+  <fact_driven_verification>
+    - ALWAYS verify user claims against actual code implementation
+    - For feature requests, aggressively check if current behavior matches user's description
+    - If code shows different intent than user describes, it might be a bug not a feature
+    - Present code evidence when challenging user assumptions
+    - Do not be agreeable - be fact-driven and question discrepancies
+    - Continue verification until facts are established
+    - A "feature request" where code shows the feature should already work is likely a bug
+
+    CRITICAL additions for thorough analysis:
+    - Trace data flow from where values are created to where they're used
+    - Look for existing variables/functions that already contain needed data
+    - Check if the issue is just missing usage of existing code
+    - Follow imports and exports to understand data availability
+    - Identify patterns in similar features that work correctly
+  </fact_driven_verification>
+
   <general_practices>
     - Always search for existing similar issues before creating a new one
-    - Search GitHub Discussions (especially feature-requests category) for related topics
+    - Check for and use repository issue templates before creating content
     - Include specific version numbers and environment details
     - Use code blocks with syntax highlighting for code snippets
     - Make titles descriptive but concise (e.g., "Dark theme: Submit button invisible due to white-on-grey text")
     - For bugs, always test if the issue is reproducible
     - Include screenshots or mockups when relevant (ask user to provide)
     - Link to related issues or PRs if found during exploration
-    - Add "Closes #[number]" for discussions that would be fully addressed by the issue
-    - Add "Related to #[number]" for partially related discussions
+
+    CRITICAL: Use concrete examples throughout:
+    - Show actual data values, not just descriptions
+    - Include specific file paths and line numbers
+    - Demonstrate the data flow with real examples
+    - Bad: "The value is incorrect"
+    - Good: "The function returns '123' when it should return '456'"
   </general_practices>
 
   <contributor_specific>
-    - Only explore codebase if user wants to contribute
+    - Only perform issue scoping if user wants to contribute
     - Reference specific files and line numbers from codebase exploration
     - Ensure technical proposals align with project architecture
-    - Include implementation steps and technical analysis
+    - Include implementation steps and issue scoping
     - Provide clear acceptance criteria in Given/When/Then format
     - Consider trade-offs and alternative approaches
+
+    CRITICAL: Prioritize simple solutions:
+    - ALWAYS check if needed functionality already exists before proposing new code
+    - Look for existing variables that just need to be passed/used differently
+    - Prefer using existing patterns over creating new ones
+    - The best fix often involves minimal code changes
+    - Example: "Use existing `modeInfo` from line 234 in export" vs "Create new mode tracking system"
   </contributor_specific>
 
+  <backwards_compatibility_focus>
+    ALWAYS consider backwards compatibility:
+    - Think about existing data/configurations already in use
+    - Propose solutions that handle both old and new formats gracefully
+    - Consider migration paths for existing users
+    - Document any breaking changes clearly
+    - Prefer additive changes over breaking changes when possible
+  </backwards_compatibility_focus>
+
   <communication_guidelines>
     - Be supportive and encouraging to problem reporters
     - Don't overwhelm users with technical questions upfront
     - Clearly indicate when technical sections are optional
     - Guide contributors through the additional requirements
     - Make the "submit now" option clear for problem reporters
+    - When presenting template choices, include template descriptions to help users choose
+    - Explain that you're using the repository's own templates for consistency
   </communication_guidelines>
+
+  <template_best_practices>
+    <practice name="template_detection">
+      Always check these locations in order:
+      1. .github/ISSUE_TEMPLATE/*.yml or *.yaml (GitHub form syntax)
+      2. .github/ISSUE_TEMPLATE/*.md (Markdown templates)
+      3. .github/issue_template.md (single template)
+      4. .github/ISSUE_TEMPLATE.md (alternate naming)
+    </practice>
+
+    <practice name="template_parsing">
+      For YAML templates:
+      - Extract form elements and convert to appropriate markdown sections
+      - Preserve required field indicators
+      - Include field descriptions as context
+      - Respect dropdown options and checkbox lists
+
+      For Markdown templates:
+      - Parse front matter for metadata
+      - Identify section headers and structure
+      - Replace placeholder text with actual information
+      - Maintain formatting and hierarchy
+    </practice>
+
+    <practice name="template_filling">
+      - Map gathered information to template sections intelligently
+      - Don't leave placeholder text in the final issue
+      - Add code investigation findings to relevant sections
+      - Include contributor scoping in appropriate section if applicable
+      - Preserve the template's intended structure and flow
+    </practice>
+
+    <practice name="no_template_handling">
+      When no templates exist:
+      - Create minimal, focused templates
+      - Use simple section headers
+      - Focus on essential information only
+      - Adapt structure based on issue type
+      - Don't overwhelm with unnecessary fields
+    </practice>
+  </template_best_practices>
+  <technical_accuracy_guidelines>
+    <guideline name="thorough_code_analysis">
+      Before proposing ANY solution:
+      1. Use codebase_search extensively to find all related code
+      2. Read multiple files to understand the full context
+      3. Trace variable usage from creation to consumption
+      4. Look for similar working features to understand patterns
+      5. Identify what already exists vs what's actually missing
+    </guideline>
+
+    <guideline name="simplicity_first">
+      When designing solutions:
+      1. Check if the data/function already exists somewhere
+      2. Look for configuration options before code changes
+      3. Prefer passing existing variables over creating new ones
+      4. Use established patterns from similar features
+      5. Aim for minimal diff size
+    </guideline>
+
+    <guideline name="precise_technical_details">
+      Always include:
+      - Exact file paths and line numbers
+      - Variable/function names as they appear in code
+      - Before/after code snippets showing minimal changes
+      - Clear explanation of why the simple fix works
+    </guideline>
+  </technical_accuracy_guidelines>
 </best_practices>

.roo/rules-issue-writer/4_common_mistakes_to_avoid.xml

@@ -1,4 +1,13 @@
 <common_mistakes_to_avoid>
+  <mode_initialization_mistakes>
+    - CRITICAL: Asking "What would you like to do?" when mode starts
+    - Waiting for user to say "create an issue" or "make me an issue"
+    - Not treating the first user message as the issue description
+    - Delaying the workflow start with unnecessary questions
+    - Asking if they want to create an issue when they've already chosen this mode
+    - Not immediately beginning repository detection and codebase discovery
+  </mode_initialization_mistakes>
+
   <problem_reporting_mistakes>
     - Vague descriptions like "doesn't work" or "broken"
     - Missing reproduction steps for bugs
@@ -12,19 +21,106 @@
 
   <workflow_mistakes>
     - Asking for technical details from non-contributing users
-    - Exploring codebase before confirming user wants to contribute
+    - Performing issue scoping before confirming user wants to contribute
     - Requiring acceptance criteria from problem reporters
     - Making the process too complex for simple problem reports
     - Not clearly indicating the "submit now" option
     - Overwhelming users with contributor requirements upfront
+    - Using hardcoded templates instead of repository templates
+    - Not checking for issue templates before creating content
+    - Ignoring template metadata like labels and assignees
   </workflow_mistakes>
 
   <contributor_mistakes>
     - Starting implementation before approval
-    - Not providing detailed technical analysis when contributing
+    - Not providing detailed issue scoping when contributing
     - Missing acceptance criteria for contributed features
     - Forgetting to include technical context from code exploration
     - Not considering trade-offs and alternatives
     - Proposing solutions without understanding current architecture
   </contributor_mistakes>
+
+  <technical_analysis_mistakes>
+    <mistake>Not tracing data flow completely through the system</mistake>
+    <impact>Missing that data already exists leads to proposing unnecessary new code</impact>
+    <correct_approach>
+      - Use codebase_search extensively to find ALL related code
+      - Trace variables from creation to consumption
+      - Check if needed data is already calculated but not used
+      - Look for similar working features as patterns
+    </correct_approach>
+    <example>
+      Bad: "Add mode tracking to import function"
+      Good: "The export already includes mode info at line 234, just use it in import at line 567"
+    </example>
+  </technical_analysis_mistakes>
+
+  <solution_design_mistakes>
+    <mistake>Proposing complex new systems when simple fixes exist</mistake>
+    <impact>Creates unnecessary complexity, maintenance burden, and potential bugs</impact>
+    <correct_approach>
+      - ALWAYS check if functionality already exists first
+      - Look for minimal changes that solve the problem
+      - Prefer using existing variables/functions differently
+      - Aim for the smallest possible diff
+    </correct_approach>
+    <example>
+      Bad: "Create new state management system for mode tracking"
+      Good: "Pass existing modeInfo variable from line 45 to the function at line 78"
+    </example>
+  </solution_design_mistakes>
+
+  <code_verification_mistakes>
+    <mistake>Not reading actual code before proposing solutions</mistake>
+    <impact>Solutions don't match the actual codebase structure</impact>
+    <correct_approach>
+      - Always read the relevant files first
+      - Verify exact line numbers and content
+      - Check imports/exports to understand data availability
+      - Look at similar features that work correctly
+    </correct_approach>
+  </code_verification_mistakes>
+
+  <pattern_recognition_mistakes>
+    <mistake>Creating new patterns instead of following existing ones</mistake>
+    <impact>Inconsistent codebase, harder to maintain</impact>
+    <correct_approach>
+      - Find similar features that work correctly
+      - Follow the same patterns and structures
+      - Reuse existing utilities and helpers
+      - Maintain consistency with the codebase style
+    </correct_approach>
+  </pattern_recognition_mistakes>
+
+  <template_usage_mistakes>
+    <mistake>Using hardcoded templates when repository templates exist</mistake>
+    <impact>Issues don't follow repository conventions, may be rejected or need reformatting</impact>
+    <correct_approach>
+      - Always check .github/ISSUE_TEMPLATE/ directory first
+      - Parse and use repository templates when available
+      - Only create generic templates when none exist
+    </correct_approach>
+  </template_usage_mistakes>
+
+  <template_parsing_mistakes>
+    <mistake>Not properly parsing YAML template structure</mistake>
+    <impact>Missing required fields, incorrect formatting, lost metadata</impact>
+    <correct_approach>
+      - Parse YAML templates to extract all form elements
+      - Convert form elements to appropriate markdown sections
+      - Preserve field requirements and descriptions
+      - Maintain dropdown options and checkbox lists
+    </correct_approach>
+  </template_parsing_mistakes>
+
+  <template_filling_mistakes>
+    <mistake>Leaving placeholder text in final issue</mistake>
+    <impact>Unprofessional appearance, confusion about what information is needed</impact>
+    <correct_approach>
+      - Replace all placeholders with actual information
+      - Remove instruction text meant for template users
+      - Fill every section with relevant content
+      - Add "N/A" for truly inapplicable sections
+    </correct_approach>
+  </template_filling_mistakes>
 </common_mistakes_to_avoid>