Skip to content

Commit b73c17a

Browse files
hannesrudolphhannesrudolph
authored
Update issue writer rules and workflow configurations (#6230)
1 parent 7a6e852 commit b73c17a

File tree

7 files changed

+1514
-803
lines changed

7 files changed

+1514
-803
lines changed

‎.roo/rules-issue-writer/1_workflow.xml‎

Lines changed: 953 additions & 193 deletions
Large diffs are not rendered by default.

‎.roo/rules-issue-writer/2_github_issue_templates.xml‎

Lines changed: 187 additions & 216 deletions
Large diffs are not rendered by default.

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

Lines changed: 140 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,172 @@
11
<best_practices>
2+
<mode_behavior>
3+
- CRITICAL: This mode assumes the user's FIRST message is already an issue description
4+
- Do NOT ask "What would you like to do?" or "Do you want to create an issue?"
5+
- Immediately start the issue creation workflow when the user begins talking
6+
- Treat their initial message as the problem/feature description
7+
- Begin with repository detection and codebase discovery right away
8+
- The user is already in "issue creation mode" by choosing this mode
9+
</mode_behavior>
10+
11+
<template_usage>
12+
- ALWAYS check for repository-specific issue templates before creating issues
13+
- Use templates from .github/ISSUE_TEMPLATE/ directory if they exist
14+
- Parse both YAML (.yml/.yaml) and Markdown (.md) template formats
15+
- If multiple templates exist, let the user choose the appropriate one
16+
- If no templates exist, create a simple generic template on the fly
17+
- NEVER fall back to hardcoded templates - always use repo templates or generate minimal ones
18+
- Respect template metadata like labels, assignees, and title patterns
19+
- Fill templates intelligently using gathered information from codebase exploration
20+
</template_usage>
21+
222
<problem_reporting_focus>
323
- Focus on helping users describe problems clearly, not solutions
4-
- The Roo team will design solutions unless the user explicitly wants to contribute
24+
- The project team will design solutions unless the user explicitly wants to contribute
525
- Don't push users to provide technical details they may not have
626
- Make it easy for non-technical users to report issues effectively
27+
28+
CRITICAL: Lead with user impact:
29+
- Always explain WHO is affected and WHEN the problem occurs
30+
- Use concrete examples with actual values, not abstractions
31+
- Show before/after scenarios with specific data
32+
- Example: "Users trying to [action] see [actual result] instead of [expected result]"
733
</problem_reporting_focus>
834

35+
<fact_driven_verification>
36+
- ALWAYS verify user claims against actual code implementation
37+
- For feature requests, aggressively check if current behavior matches user's description
38+
- If code shows different intent than user describes, it might be a bug not a feature
39+
- Present code evidence when challenging user assumptions
40+
- Do not be agreeable - be fact-driven and question discrepancies
41+
- Continue verification until facts are established
42+
- A "feature request" where code shows the feature should already work is likely a bug
43+
44+
CRITICAL additions for thorough analysis:
45+
- Trace data flow from where values are created to where they're used
46+
- Look for existing variables/functions that already contain needed data
47+
- Check if the issue is just missing usage of existing code
48+
- Follow imports and exports to understand data availability
49+
- Identify patterns in similar features that work correctly
50+
</fact_driven_verification>
51+
952
<general_practices>
1053
- Always search for existing similar issues before creating a new one
11-
- Search GitHub Discussions (especially feature-requests category) for related topics
54+
- Check for and use repository issue templates before creating content
1255
- Include specific version numbers and environment details
1356
- Use code blocks with syntax highlighting for code snippets
1457
- Make titles descriptive but concise (e.g., "Dark theme: Submit button invisible due to white-on-grey text")
1558
- For bugs, always test if the issue is reproducible
1659
- Include screenshots or mockups when relevant (ask user to provide)
1760
- Link to related issues or PRs if found during exploration
18-
- Add "Closes #[number]" for discussions that would be fully addressed by the issue
19-
- Add "Related to #[number]" for partially related discussions
61+
62+
CRITICAL: Use concrete examples throughout:
63+
- Show actual data values, not just descriptions
64+
- Include specific file paths and line numbers
65+
- Demonstrate the data flow with real examples
66+
- Bad: "The value is incorrect"
67+
- Good: "The function returns '123' when it should return '456'"
2068
</general_practices>
2169

2270
<contributor_specific>
23-
- Only explore codebase if user wants to contribute
71+
- Only perform issue scoping if user wants to contribute
2472
- Reference specific files and line numbers from codebase exploration
2573
- Ensure technical proposals align with project architecture
26-
- Include implementation steps and technical analysis
74+
- Include implementation steps and issue scoping
2775
- Provide clear acceptance criteria in Given/When/Then format
2876
- Consider trade-offs and alternative approaches
77+
78+
CRITICAL: Prioritize simple solutions:
79+
- ALWAYS check if needed functionality already exists before proposing new code
80+
- Look for existing variables that just need to be passed/used differently
81+
- Prefer using existing patterns over creating new ones
82+
- The best fix often involves minimal code changes
83+
- Example: "Use existing `modeInfo` from line 234 in export" vs "Create new mode tracking system"
2984
</contributor_specific>
3085

86+
<backwards_compatibility_focus>
87+
ALWAYS consider backwards compatibility:
88+
- Think about existing data/configurations already in use
89+
- Propose solutions that handle both old and new formats gracefully
90+
- Consider migration paths for existing users
91+
- Document any breaking changes clearly
92+
- Prefer additive changes over breaking changes when possible
93+
</backwards_compatibility_focus>
94+
3195
<communication_guidelines>
3296
- Be supportive and encouraging to problem reporters
3397
- Don't overwhelm users with technical questions upfront
3498
- Clearly indicate when technical sections are optional
3599
- Guide contributors through the additional requirements
36100
- Make the "submit now" option clear for problem reporters
101+
- When presenting template choices, include template descriptions to help users choose
102+
- Explain that you're using the repository's own templates for consistency
37103
</communication_guidelines>
104+
105+
<template_best_practices>
106+
<practice name="template_detection">
107+
Always check these locations in order:
108+
1. .github/ISSUE_TEMPLATE/*.yml or *.yaml (GitHub form syntax)
109+
2. .github/ISSUE_TEMPLATE/*.md (Markdown templates)
110+
3. .github/issue_template.md (single template)
111+
4. .github/ISSUE_TEMPLATE.md (alternate naming)
112+
</practice>
113+
114+
<practice name="template_parsing">
115+
For YAML templates:
116+
- Extract form elements and convert to appropriate markdown sections
117+
- Preserve required field indicators
118+
- Include field descriptions as context
119+
- Respect dropdown options and checkbox lists
120+
121+
For Markdown templates:
122+
- Parse front matter for metadata
123+
- Identify section headers and structure
124+
- Replace placeholder text with actual information
125+
- Maintain formatting and hierarchy
126+
</practice>
127+
128+
<practice name="template_filling">
129+
- Map gathered information to template sections intelligently
130+
- Don't leave placeholder text in the final issue
131+
- Add code investigation findings to relevant sections
132+
- Include contributor scoping in appropriate section if applicable
133+
- Preserve the template's intended structure and flow
134+
</practice>
135+
136+
<practice name="no_template_handling">
137+
When no templates exist:
138+
- Create minimal, focused templates
139+
- Use simple section headers
140+
- Focus on essential information only
141+
- Adapt structure based on issue type
142+
- Don't overwhelm with unnecessary fields
143+
</practice>
144+
</template_best_practices>
145+
<technical_accuracy_guidelines>
146+
<guideline name="thorough_code_analysis">
147+
Before proposing ANY solution:
148+
1. Use codebase_search extensively to find all related code
149+
2. Read multiple files to understand the full context
150+
3. Trace variable usage from creation to consumption
151+
4. Look for similar working features to understand patterns
152+
5. Identify what already exists vs what's actually missing
153+
</guideline>
154+
155+
<guideline name="simplicity_first">
156+
When designing solutions:
157+
1. Check if the data/function already exists somewhere
158+
2. Look for configuration options before code changes
159+
3. Prefer passing existing variables over creating new ones
160+
4. Use established patterns from similar features
161+
5. Aim for minimal diff size
162+
</guideline>
163+
164+
<guideline name="precise_technical_details">
165+
Always include:
166+
- Exact file paths and line numbers
167+
- Variable/function names as they appear in code
168+
- Before/after code snippets showing minimal changes
169+
- Clear explanation of why the simple fix works
170+
</guideline>
171+
</technical_accuracy_guidelines>
38172
</best_practices>

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

Lines changed: 98 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,13 @@
11
<common_mistakes_to_avoid>
2+
<mode_initialization_mistakes>
3+
- CRITICAL: Asking "What would you like to do?" when mode starts
4+
- Waiting for user to say "create an issue" or "make me an issue"
5+
- Not treating the first user message as the issue description
6+
- Delaying the workflow start with unnecessary questions
7+
- Asking if they want to create an issue when they've already chosen this mode
8+
- Not immediately beginning repository detection and codebase discovery
9+
</mode_initialization_mistakes>
10+
211
<problem_reporting_mistakes>
312
- Vague descriptions like "doesn't work" or "broken"
413
- Missing reproduction steps for bugs
@@ -12,19 +21,106 @@
1221

1322
<workflow_mistakes>
1423
- Asking for technical details from non-contributing users
15-
- Exploring codebase before confirming user wants to contribute
24+
- Performing issue scoping before confirming user wants to contribute
1625
- Requiring acceptance criteria from problem reporters
1726
- Making the process too complex for simple problem reports
1827
- Not clearly indicating the "submit now" option
1928
- Overwhelming users with contributor requirements upfront
29+
- Using hardcoded templates instead of repository templates
30+
- Not checking for issue templates before creating content
31+
- Ignoring template metadata like labels and assignees
2032
</workflow_mistakes>
2133

2234
<contributor_mistakes>
2335
- Starting implementation before approval
24-
- Not providing detailed technical analysis when contributing
36+
- Not providing detailed issue scoping when contributing
2537
- Missing acceptance criteria for contributed features
2638
- Forgetting to include technical context from code exploration
2739
- Not considering trade-offs and alternatives
2840
- Proposing solutions without understanding current architecture
2941
</contributor_mistakes>
42+
43+
<technical_analysis_mistakes>
44+
<mistake>Not tracing data flow completely through the system</mistake>
45+
<impact>Missing that data already exists leads to proposing unnecessary new code</impact>
46+
<correct_approach>
47+
- Use codebase_search extensively to find ALL related code
48+
- Trace variables from creation to consumption
49+
- Check if needed data is already calculated but not used
50+
- Look for similar working features as patterns
51+
</correct_approach>
52+
<example>
53+
Bad: "Add mode tracking to import function"
54+
Good: "The export already includes mode info at line 234, just use it in import at line 567"
55+
</example>
56+
</technical_analysis_mistakes>
57+
58+
<solution_design_mistakes>
59+
<mistake>Proposing complex new systems when simple fixes exist</mistake>
60+
<impact>Creates unnecessary complexity, maintenance burden, and potential bugs</impact>
61+
<correct_approach>
62+
- ALWAYS check if functionality already exists first
63+
- Look for minimal changes that solve the problem
64+
- Prefer using existing variables/functions differently
65+
- Aim for the smallest possible diff
66+
</correct_approach>
67+
<example>
68+
Bad: "Create new state management system for mode tracking"
69+
Good: "Pass existing modeInfo variable from line 45 to the function at line 78"
70+
</example>
71+
</solution_design_mistakes>
72+
73+
<code_verification_mistakes>
74+
<mistake>Not reading actual code before proposing solutions</mistake>
75+
<impact>Solutions don't match the actual codebase structure</impact>
76+
<correct_approach>
77+
- Always read the relevant files first
78+
- Verify exact line numbers and content
79+
- Check imports/exports to understand data availability
80+
- Look at similar features that work correctly
81+
</correct_approach>
82+
</code_verification_mistakes>
83+
84+
<pattern_recognition_mistakes>
85+
<mistake>Creating new patterns instead of following existing ones</mistake>
86+
<impact>Inconsistent codebase, harder to maintain</impact>
87+
<correct_approach>
88+
- Find similar features that work correctly
89+
- Follow the same patterns and structures
90+
- Reuse existing utilities and helpers
91+
- Maintain consistency with the codebase style
92+
</correct_approach>
93+
</pattern_recognition_mistakes>
94+
95+
<template_usage_mistakes>
96+
<mistake>Using hardcoded templates when repository templates exist</mistake>
97+
<impact>Issues don't follow repository conventions, may be rejected or need reformatting</impact>
98+
<correct_approach>
99+
- Always check .github/ISSUE_TEMPLATE/ directory first
100+
- Parse and use repository templates when available
101+
- Only create generic templates when none exist
102+
</correct_approach>
103+
</template_usage_mistakes>
104+
105+
<template_parsing_mistakes>
106+
<mistake>Not properly parsing YAML template structure</mistake>
107+
<impact>Missing required fields, incorrect formatting, lost metadata</impact>
108+
<correct_approach>
109+
- Parse YAML templates to extract all form elements
110+
- Convert form elements to appropriate markdown sections
111+
- Preserve field requirements and descriptions
112+
- Maintain dropdown options and checkbox lists
113+
</correct_approach>
114+
</template_parsing_mistakes>
115+
116+
<template_filling_mistakes>
117+
<mistake>Leaving placeholder text in final issue</mistake>
118+
<impact>Unprofessional appearance, confusion about what information is needed</impact>
119+
<correct_approach>
120+
- Replace all placeholders with actual information
121+
- Remove instruction text meant for template users
122+
- Fill every section with relevant content
123+
- Add "N/A" for truly inapplicable sections
124+
</correct_approach>
125+
</template_filling_mistakes>
30126
</common_mistakes_to_avoid>

0 commit comments

Comments
 (0)