Skip to content

Commit 2ecf2ce

Browse files
hannesrudolphhannesrudolph
authored
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 parent a3106bf commit 2ecf2ce

File tree

7 files changed

+646
-843
lines changed

7 files changed

+646
-843
lines changed

‎.roo/rules-docs-extractor/1_extraction_workflow.xml‎

Lines changed: 91 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,28 @@
11
<extraction_workflow>
22
<mode_overview>
3-
The Docs Extractor mode performs comprehensive analysis of features and components
4-
to generate multi-audience documentation. It extracts technical details, business logic,
5-
user workflows, and all related information to create documentation suitable for
6-
end-users, developers, administrators, and stakeholders.
3+
The Docs Extractor mode analyzes features to generate documentation.
4+
It extracts technical details, business logic, and user workflows
5+
for different audiences.
76
</mode_overview>
87

98
<initialization_phase>
109
<step number="1">
11-
<title>Understand Documentation Request</title>
10+
<title>Parse Request</title>
1211
<actions>
13-
<action>Parse the user's request to identify the feature or component.</action>
14-
<action>Determine if the user has provided a documentation section for review or is requesting new documentation.</action>
15-
<action>Default to user-friendly documentation unless technical docs are specifically requested.</action>
16-
<action>Focus on practical benefits and real-world usage.</action>
17-
<action>Note any specific aspects the user wants emphasized.</action>
12+
<action>Identify the feature or component in the user's request.</action>
13+
<action>Determine if the request is for a review or to generate new documentation.</action>
14+
<action>Default to user-friendly docs unless technical output is requested.</action>
15+
<action>Note any specific areas to emphasize.</action>
1816
</actions>
19-
<note>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.</note>
17+
<note>The initial request determines the workflow path (review vs. generation).</note>
2018
</step>
2119

2220
<step number="2">
23-
<title>Initial Feature Discovery</title>
21+
<title>Discover Feature</title>
2422
<actions>
25-
<action>Use semantic search to find all related code</action>
26-
<action>Identify entry points and main components</action>
27-
<action>Map high-level architecture</action>
23+
<action>Find related code with semantic search.</action>
24+
<action>Identify entry points and components.</action>
25+
<action>Map the high-level architecture.</action>
2826
</actions>
2927
<tool_use><![CDATA[
3028
<codebase_search>
@@ -36,111 +34,111 @@
3634

3735
<analysis_phases>
3836
<phase name="code_analysis">
39-
<title>Technical Implementation Analysis</title>
37+
<title>Code Analysis</title>
4038
<steps>
4139
<step>
42-
<action>Analyze source code structure</action>
40+
<action>Analyze code structure</action>
4341
<details>
44-
- Identify classes, functions, and modules
45-
- Extract method signatures and parameters
46-
- Document return types and data structures
47-
- Map inheritance and composition relationships
42+
- Identify classes, functions, modules
43+
- Extract method signatures, parameters
44+
- Document return types, data structures
45+
- Map inheritance and composition
4846
</details>
4947
</step>
5048
<step>
51-
<action>Extract API specifications</action>
49+
<action>Extract APIs</action>
5250
<details>
53-
- REST endpoints with methods and parameters
54-
- GraphQL schemas and resolvers
55-
- WebSocket events and handlers
56-
- RPC interfaces and protocols
51+
- REST endpoints
52+
- GraphQL schemas
53+
- WebSocket events
54+
- RPC interfaces
5755
</details>
5856
</step>
5957
<step>
60-
<action>Document configuration options</action>
58+
<action>Document configuration</action>
6159
<details>
6260
- Environment variables
63-
- Configuration files and schemas
64-
- Feature flags and toggles
61+
- Config files and schemas
62+
- Feature flags
6563
- Runtime parameters
6664
</details>
6765
</step>
6866
</steps>
6967
</phase>
7068

7169
<phase name="business_logic_analysis">
72-
<title>Business Logic and Workflow Extraction</title>
70+
<title>Business Logic Extraction</title>
7371
<steps>
7472
<step>
75-
<action>Map user workflows</action>
73+
<action>Map workflows</action>
7674
<details>
77-
- User journey through the feature
78-
- Decision points and branching logic
79-
- State transitions and lifecycle
80-
- User roles and permissions
75+
- User journey
76+
- Decision points and branching
77+
- State transitions
78+
- Roles and permissions
8179
</details>
8280
</step>
8381
<step>
8482
<action>Document business rules</action>
8583
<details>
86-
- Validation logic and constraints
87-
- Calculation formulas and algorithms
84+
- Validation logic
85+
- Formulas and algorithms
8886
- Business process implementations
89-
- Compliance and regulatory requirements
87+
- Compliance requirements
9088
</details>
9189
</step>
9290
<step>
9391
<action>Identify use cases</action>
9492
<details>
95-
- Primary use cases and scenarios
96-
- Edge cases and special conditions
97-
- Error scenarios and recovery
98-
- Performance considerations
93+
- Primary use cases
94+
- Edge cases
95+
- Error scenarios
96+
- Performance factors
9997
</details>
10098
</step>
10199
</steps>
102100
</phase>
103101

104102
<phase name="integration_analysis">
105-
<title>Dependencies and Integration Analysis</title>
103+
<title>Dependency Analysis</title>
106104
<steps>
107105
<step>
108-
<action>Map external dependencies</action>
106+
<action>Map dependencies</action>
109107
<details>
110-
- Third-party libraries and versions
108+
- Third-party libraries
111109
- External services and APIs
112-
- Database connections and schemas
113-
- Message queues and event systems
110+
- Database connections
111+
- Message queues
114112
</details>
115113
</step>
116114
<step>
117115
<action>Document integration points</action>
118116
<details>
119-
- Incoming webhooks and callbacks
117+
- Incoming webhooks
120118
- Outgoing API calls
121-
- Event publishers and subscribers
122-
- Shared data stores and caches
119+
- Event publishers/subscribers
120+
- Shared data stores
123121
</details>
124122
</step>
125123
<step>
126124
<action>Analyze data flow</action>
127125
<details>
128-
- Input data sources and formats
129-
- Data transformations and mappings
126+
- Data sources and formats
127+
- Data transformations
130128
- Output formats and destinations
131-
- Data retention and lifecycle
129+
- Data retention policies
132130
</details>
133131
</step>
134132
</steps>
135133
</phase>
136134

137135
<phase name="quality_analysis">
138-
<title>Quality and Testing Analysis</title>
136+
<title>Test Analysis</title>
139137
<steps>
140138
<step>
141139
<action>Assess test coverage</action>
142140
<details>
143-
- Unit test coverage and quality
141+
- Unit test coverage
144142
- Integration test scenarios
145143
- End-to-end test flows
146144
- Performance test results
@@ -150,89 +148,89 @@
150148
<action>Document error handling</action>
151149
<details>
152150
- Error types and codes
153-
- Exception handling strategies
151+
- Exception handling
154152
- Fallback mechanisms
155153
- Recovery procedures
156154
</details>
157155
</step>
158156
<step>
159157
<action>Identify quality metrics</action>
160158
<details>
161-
- Code complexity metrics
159+
- Code complexity
162160
- Performance benchmarks
163-
- Security vulnerability assessments
164-
- Maintainability indices
161+
- Security vulnerabilities
162+
- Maintainability scores
165163
</details>
166164
</step>
167165
</steps>
168166
</phase>
169167

170168
<phase name="security_analysis">
171-
<title>Security and Compliance Analysis</title>
169+
<title>Security Analysis</title>
172170
<steps>
173171
<step>
174-
<action>Document security measures</action>
172+
<action>Document security</action>
175173
<details>
176-
- Authentication mechanisms
177-
- Authorization and access control
178-
- Data encryption methods
179-
- Security headers and policies
174+
- Auth mechanisms
175+
- Access control
176+
- Data encryption
177+
- Security policies
180178
</details>
181179
</step>
182180
<step>
183181
<action>Identify vulnerabilities</action>
184182
<details>
185183
- Known security issues
186-
- Potential attack vectors
187-
- Mitigation strategies
188-
- Security best practices
184+
- Attack vectors
185+
- Mitigation
186+
- Best practices
189187
</details>
190188
</step>
191189
<step>
192-
<action>Compliance requirements</action>
190+
<action>Check compliance</action>
193191
<details>
194-
- Regulatory compliance (GDPR, HIPAA, etc.)
195-
- Industry standards adherence
192+
- Regulatory compliance (GDPR, etc.)
193+
- Industry standards
196194
- Audit trail requirements
197-
- Data privacy considerations
195+
- Data privacy
198196
</details>
199197
</step>
200198
</steps>
201199
</phase>
202200
</analysis_phases>
203201

204202
<documentation_generation>
205-
<note>This phase has two paths: Reviewing existing docs or Generating new docs. The path taken is determined in the initialization phase.</note>
203+
<note>Workflow branches here: review existing docs or generate new docs.</note>
206204
<step number="1">
207-
<title>Path 1: Review and Recommend Improvements</title>
208-
<note>This path is followed if the user provided a documentation section for review.</note>
205+
<title>Path 1: Review and Recommend</title>
206+
<note>Used when a document is provided for review.</note>
209207
<actions>
210-
<action>Compare the provided documentation against the analysis of the codebase.</action>
211-
<action>Identify inaccuracies (technical, logical), omissions, and areas for improvement.</action>
212-
<action>Categorize inaccuracies by severity (e.g., Critical, Major, Minor, Suggestion).</action>
213-
<action>Formulate a structured recommendation in the chat, suitable for being copied to the docs team.</action>
214-
<action>Do not write any files or make changes yourself.</action>
215-
<action>The final output in the chat should ONLY be the structured recommendation, without any preceding conversational text.</action>
208+
<action>Compare provided docs against codebase analysis.</action>
209+
<action>Identify inaccuracies, omissions, and areas for improvement.</action>
210+
<action>Categorize issues by severity (Critical, Major, Minor).</action>
211+
<action>Formulate a structured recommendation in chat.</action>
212+
<action>Do not write files.</action>
213+
<action>Final output is only the recommendation.</action>
216214
</actions>
217215
</step>
218216
<step number="2">
219-
<title>Path 2: Generate New Documentation</title>
220-
<note>This path is followed if the user requested new documentation.</note>
217+
<title>Path 2: Generate Documentation</title>
218+
<note>Used when new documentation is requested.</note>
221219
<actions>
222-
<action>Choose a documentation style (e.g., user-focused or comprehensive) from `2_documentation_patterns.xml`.</action>
223-
<action>Structure the documentation with clear sections, examples, and user-friendly elements.</action>
224-
<action>Create a `DOCS-TEMP-[feature].md` file with the generated content.</action>
225-
<action>Use a conversational tone and practical examples from `7_user_friendly_examples.xml`.</action>
220+
<action>Select a template from `2_documentation_patterns.xml`.</action>
221+
<action>Structure the document with clear sections and examples.</action>
222+
<action>Create `DOCS-TEMP-[feature].md` with generated content.</action>
223+
<action>Apply tone and examples from `7_user_friendly_examples.xml`.</action>
226224
</actions>
227225
</step>
228226
</documentation_generation>
229227

230228
<completion_criteria>
231-
<criterion>All code paths have been analyzed</criterion>
232-
<criterion>Business logic is fully documented</criterion>
233-
<criterion>Integration points are mapped</criterion>
234-
<criterion>Security considerations are addressed</criterion>
235-
<criterion>Documentation serves all target audiences</criterion>
236-
<criterion>Metadata and cross-references are complete</criterion>
229+
<criterion>Code paths analyzed</criterion>
230+
<criterion>Business logic documented</criterion>
231+
<criterion>Integration points mapped</criterion>
232+
<criterion>Security addressed</criterion>
233+
<criterion>Audience needs met</criterion>
234+
<criterion>Metadata and links are complete</criterion>
237235
</completion_criteria>
238236
</extraction_workflow>

0 commit comments

Comments
 (0)