Skip to content

Commit 82a3212

Browse files
hannesrudolphhannesrudolph
authored
docs: update docs extractor mode configuration and rules (#6373)
1 parent b117c0f commit 82a3212

File tree

6 files changed

+1339
-972
lines changed

6 files changed

+1339
-972
lines changed

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

Lines changed: 176 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,34 @@
11
<extraction_workflow>
22
<mode_overview>
3-
The Docs Extractor mode analyzes features to generate documentation.
4-
It extracts technical details, business logic, and user workflows
5-
for different audiences.
3+
The Docs Extractor mode has two primary functions:
4+
1. Extract technical and non-technical details about features to provide to documentation teams
5+
2. Verify existing documentation for factual accuracy against the codebase
6+
7+
This mode does not generate final documentation but provides detailed analysis and verification.
68
</mode_overview>
79

810
<initialization_phase>
911
<step number="1">
1012
<title>Parse Request</title>
1113
<actions>
1214
<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>
15+
<action>Determine if the request is for extraction or verification.</action>
16+
<action>For extraction: Note what level of detail is needed (technical vs non-technical).</action>
17+
<action>For verification: Identify the documentation to be verified.</action>
18+
<action>Note any specific areas to emphasize or check.</action>
1619
</actions>
17-
<note>The initial request determines the workflow path (review vs. generation).</note>
20+
<note>The mode branches into extraction or verification based on the request.</note>
1821
</step>
1922

2023
<step number="2">
2124
<title>Discover Feature</title>
2225
<actions>
23-
<action>Find related code with semantic search.</action>
26+
<action>Locate relevant code using appropriate search methods.</action>
2427
<action>Identify entry points and components.</action>
2528
<action>Map the high-level architecture.</action>
29+
<action>Use any combination of tools to understand the feature.</action>
2630
</actions>
27-
<tool_use><![CDATA[
28-
<codebase_search>
29-
<query>[feature name] implementation main entry point</query>
30-
</codebase_search>
31-
]]></tool_use>
31+
<note>Use the most effective discovery method for the situation - file exploration, search, or direct navigation.</note>
3232
</step>
3333
</initialization_phase>
3434

@@ -66,22 +66,68 @@
6666
</steps>
6767
</phase>
6868

69+
<phase name="ui_ux_analysis">
70+
<title>UI/UX and User Experience Analysis</title>
71+
<steps>
72+
<step>
73+
<action>Analyze user interface components</action>
74+
<details>
75+
- UI components and their interactions
76+
- Forms, buttons, navigation elements
77+
- Visual feedback and loading states
78+
- Responsive design considerations
79+
- Accessibility features
80+
</details>
81+
</step>
82+
<step>
83+
<action>Map user journeys and interactions</action>
84+
<details>
85+
- Step-by-step user workflows
86+
- Click paths and navigation flows
87+
- User decision points
88+
- Input validation and error messaging
89+
- Success and failure scenarios
90+
</details>
91+
</step>
92+
<step>
93+
<action>Document user experience elements</action>
94+
<details>
95+
- Page layouts and information architecture
96+
- Interactive elements and their behaviors
97+
- Tooltips, help text, and guidance
98+
- Confirmation dialogs and warnings
99+
- Progress indicators and status updates
100+
</details>
101+
</step>
102+
<step>
103+
<action>Capture visual and behavioral patterns</action>
104+
<details>
105+
- Color schemes and theming
106+
- Animation and transitions
107+
- Keyboard shortcuts and accessibility
108+
- Mobile vs desktop experiences
109+
- Browser-specific considerations
110+
</details>
111+
</step>
112+
</steps>
113+
</phase>
114+
69115
<phase name="business_logic_analysis">
70116
<title>Business Logic Extraction</title>
71117
<steps>
72118
<step>
73-
<action>Map workflows</action>
119+
<action>Map workflows from user perspective</action>
74120
<details>
75-
- User journey
121+
- User journey through the feature
76122
- Decision points and branching
77-
- State transitions
78-
- Roles and permissions
123+
- State transitions visible to users
124+
- Roles and permissions affecting UI
79125
</details>
80126
</step>
81127
<step>
82128
<action>Document business rules</action>
83129
<details>
84-
- Validation logic
130+
- Validation logic and user feedback
85131
- Formulas and algorithms
86132
- Business process implementations
87133
- Compliance requirements
@@ -92,8 +138,8 @@
92138
<details>
93139
- Primary use cases
94140
- Edge cases
95-
- Error scenarios
96-
- Performance factors
141+
- Error scenarios and user recovery
142+
- Performance factors affecting UX
97143
</details>
98144
</step>
99145
</steps>
@@ -199,38 +245,117 @@
199245
</phase>
200246
</analysis_phases>
201247

202-
<documentation_generation>
203-
<note>Workflow branches here: review existing docs or generate new docs.</note>
204-
<step number="1">
205-
<title>Path 1: Review and Recommend</title>
206-
<note>Used when a document is provided for review.</note>
207-
<actions>
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>
214-
</actions>
215-
</step>
216-
<step number="2">
217-
<title>Path 2: Generate Documentation</title>
218-
<note>Used when new documentation is requested.</note>
219-
<actions>
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>
224-
</actions>
225-
</step>
226-
</documentation_generation>
248+
<workflow_paths>
249+
<path name="extraction">
250+
<title>Extract Feature Details</title>
251+
<description>Analyze and extract comprehensive details for documentation team</description>
252+
<steps>
253+
<step number="1">
254+
<title>Compile Technical Details</title>
255+
<actions>
256+
<action>List all technical components and their relationships</action>
257+
<action>Document APIs, data structures, and algorithms</action>
258+
<action>Extract configuration options and their impacts</action>
259+
<action>Identify error handling and edge cases</action>
260+
<action>Note performance characteristics and limitations</action>
261+
</actions>
262+
</step>
263+
<step number="2">
264+
<title>Extract Non-Technical Information</title>
265+
<actions>
266+
<action>Describe complete user experience and workflows</action>
267+
<action>Document UI interactions and visual elements</action>
268+
<action>Explain business logic in plain language</action>
269+
<action>Identify user benefits and use cases</action>
270+
<action>Document common scenarios with UI context</action>
271+
<action>Note prerequisites and user-facing dependencies</action>
272+
<action>Capture error messages and user guidance</action>
273+
</actions>
274+
</step>
275+
<step number="3">
276+
<title>Create Extraction Report</title>
277+
<actions>
278+
<action>Organize findings into clear categories</action>
279+
<action>Separate technical and non-technical information</action>
280+
<action>Include code snippets and examples where helpful</action>
281+
<action>Create `EXTRACTION-[feature].md` with findings</action>
282+
<action>Highlight areas that need special attention in documentation</action>
283+
</actions>
284+
<output_format>
285+
- Executive summary of the feature
286+
- UI/UX analysis and user experience
287+
- Technical details section
288+
- Non-technical/user-facing details
289+
- User workflows and interactions
290+
- Configuration and setup information
291+
- Common use cases with UI context
292+
- Error handling and user guidance
293+
- Potential documentation considerations
294+
</output_format>
295+
</step>
296+
</steps>
297+
</path>
298+
299+
<path name="verification">
300+
<title>Verify Documentation Accuracy</title>
301+
<description>Check existing documentation against codebase reality</description>
302+
<steps>
303+
<step number="1">
304+
<title>Analyze Provided Documentation</title>
305+
<actions>
306+
<action>Parse the documentation to identify claims and descriptions</action>
307+
<action>Extract technical specifications mentioned</action>
308+
<action>Note user-facing features and workflows described</action>
309+
<action>Identify configuration options and examples provided</action>
310+
</actions>
311+
</step>
312+
<step number="2">
313+
<title>Verify Against Codebase</title>
314+
<actions>
315+
<action>Check technical claims against actual implementation</action>
316+
<action>Verify API endpoints, parameters, and responses</action>
317+
<action>Confirm configuration options and defaults</action>
318+
<action>Validate code examples and snippets</action>
319+
<action>Check if described workflows match implementation</action>
320+
</actions>
321+
</step>
322+
<step number="3">
323+
<title>Create Verification Report</title>
324+
<actions>
325+
<action>Categorize findings by severity (Critical, Major, Minor)</action>
326+
<action>List all inaccuracies with correct information</action>
327+
<action>Identify missing important information</action>
328+
<action>Note outdated or deprecated content</action>
329+
<action>Provide specific corrections and suggestions</action>
330+
<action>Create `VERIFICATION-[feature].md` with findings</action>
331+
</actions>
332+
<output_format>
333+
- Verification summary (Accurate/Needs Updates)
334+
- Critical inaccuracies that could mislead users
335+
- Technical corrections needed
336+
- Missing information that should be added
337+
- Suggestions for clarity improvements
338+
- Overall recommendations
339+
</output_format>
340+
</step>
341+
</steps>
342+
</path>
343+
</workflow_paths>
227344

228345
<completion_criteria>
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>
346+
<for_extraction>
347+
<criterion>All code paths analyzed</criterion>
348+
<criterion>Technical details comprehensively extracted</criterion>
349+
<criterion>Non-technical information clearly explained</criterion>
350+
<criterion>Use cases and examples provided</criterion>
351+
<criterion>Report organized for documentation team use</criterion>
352+
</for_extraction>
353+
<for_verification>
354+
<criterion>All documentation claims verified</criterion>
355+
<criterion>Inaccuracies identified and corrected</criterion>
356+
<criterion>Missing information noted</criterion>
357+
<criterion>Suggestions for improvement provided</criterion>
358+
<criterion>Clear verification report created</criterion>
359+
</for_verification>
235360
</completion_criteria>
236361
</extraction_workflow>

0 commit comments

Comments
 (0)