Skip to content

Commit 695ee82

Browse files
hannesrudolphdaniel-lxs
hannesrudolph
authored and
daniel-lxs
committed
refactor(docs-extractor): simplify mode to focus on raw fact extraction (#11129)
1 parent 232642e commit 695ee82

File tree

7 files changed

+338
-1172
lines changed

7 files changed

+338
-1172
lines changed

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

Lines changed: 97 additions & 147 deletions
Original file line numberDiff line numberDiff line change
@@ -1,163 +1,113 @@
11
<extraction_workflow>
2-
<mode_overview>
3-
The Docs Extractor mode has exactly two workflow paths:
4-
1) Verify provided documentation for factual accuracy against the codebase
5-
2) Generate source material for user-facing docs about a requested feature or aspect of the codebase
2+
<overview>
3+
Extract raw facts from a codebase about a feature or aspect.
4+
Output is structured data for documentation teams to use.
5+
Do NOT write documentation. Do NOT format prose. Do NOT make structure decisions.
6+
</overview>
67

7-
Outputs are designed to support explanatory documentation (not merely descriptive):
8-
- Capture why users need steps and why certain actions are restricted
9-
- Surface constraints, limitations, and trade‑offs
10-
- Provide troubleshooting playbooks (symptoms → causes → fixes → prevention)
11-
- Recommend targeted visuals for complex states (not step‑by‑step screenshots)
12-
13-
This mode does not generate final user documentation; it produces verification and source-material reports for docs teams.
14-
</mode_overview>
15-
16-
<initialization_phase>
8+
<process>
179
<step number="1">
18-
<title>Parse Request</title>
10+
<title>Identify Target</title>
1911
<actions>
20-
<action>Identify the feature/aspect in the user's request.</action>
21-
<action>Decide path: verification vs. source-material generation.</action>
22-
<action>For source-material: capture audience (user or developer) and depth (overview vs task-focused).</action>
23-
<action>For verification: identify the documentation to be verified (provided text/links/files).</action>
24-
<action>Note any specific areas to emphasize or check.</action>
12+
<action>Parse the user's request to identify the feature/aspect</action>
13+
<action>Clarify scope if ambiguous (ask one question max)</action>
2514
</actions>
2615
</step>
2716

2817
<step number="2">
29-
<title>Discover Feature</title>
18+
<title>Discover Code</title>
19+
<actions>
20+
<action>Use codebase_search to find relevant files</action>
21+
<action>Identify entry points, components, and related code</action>
22+
<action>Map the boundaries of the feature</action>
23+
</actions>
24+
</step>
25+
26+
<step number="3">
27+
<title>Extract Facts</title>
28+
<actions>
29+
<action>Read code and extract facts into categories (see fact_categories)</action>
30+
<action>Record file paths as sources for each fact</action>
31+
<action>Do NOT interpret, summarize, or explain - just extract</action>
32+
</actions>
33+
</step>
34+
35+
<step number="4">
36+
<title>Output Structured Data</title>
3037
<actions>
31-
<action>Locate relevant code and assets using appropriate discovery methods.</action>
32-
<action>Identify entry points and key components that affect user experience.</action>
33-
<action>Map the high-level workflow a user follows.</action>
38+
<action>Write extraction to .roo/extraction/EXTRACT-[feature].yaml</action>
39+
<action>Use the output schema (see output_format.xml)</action>
3440
</actions>
3541
</step>
36-
</initialization_phase>
42+
</process>
43+
44+
<fact_categories>
45+
<category name="identity">
46+
<extracts>
47+
<extract>Feature name as it appears in code</extract>
48+
<extract>File paths where feature is implemented</extract>
49+
<extract>Entry points (commands, UI elements, API endpoints)</extract>
50+
</extracts>
51+
</category>
52+
53+
<category name="behavior">
54+
<extracts>
55+
<extract>What the feature does (from code logic)</extract>
56+
<extract>Inputs it accepts</extract>
57+
<extract>Outputs it produces</extract>
58+
<extract>Side effects (files created, state changed, etc.)</extract>
59+
</extracts>
60+
</category>
61+
62+
<category name="configuration">
63+
<extracts>
64+
<extract>Settings/options that affect behavior</extract>
65+
<extract>Default values</extract>
66+
<extract>Valid ranges or allowed values</extract>
67+
<extract>Where configured (settings file, env var, UI)</extract>
68+
</extracts>
69+
</category>
70+
71+
<category name="constraints">
72+
<extracts>
73+
<extract>Prerequisites and dependencies</extract>
74+
<extract>Limitations (what it cannot do)</extract>
75+
<extract>Permissions required</extract>
76+
<extract>Compatibility requirements</extract>
77+
</extracts>
78+
</category>
3779

38-
<analysis_focus>
39-
<area>UI components and their interactions</area>
40-
<area>User workflows and decision points</area>
41-
<area>Configuration that changes user-visible behavior</area>
42-
<area>Error states, messages, and recovery</area>
43-
<area>Benefits, limits, prerequisites, and version notes</area>
44-
<area>Why this exists: user goals, constraints, and design intent</area>
45-
<area>“Cannot do” boundaries: permissions, invariants, and business rules</area>
46-
<area>Troubleshooting: symptoms, likely causes, diagnostics, fixes, prevention</area>
47-
<area>Common pitfalls and anti‑patterns (what to avoid and why)</area>
48-
<area>Decision rationale and trade‑offs that affect user choices</area>
49-
<area>Complex UI states that merit visuals (criteria for screenshots/diagrams)</area>
50-
</analysis_focus>
80+
<category name="errors">
81+
<extracts>
82+
<extract>Error conditions in code</extract>
83+
<extract>Error messages (exact text)</extract>
84+
<extract>Recovery paths in code</extract>
85+
</extracts>
86+
</category>
5187

52-
<workflow_paths>
53-
<path name="source_material">
54-
<title>Generate Source Material for User-Facing Docs</title>
55-
<description>Extract concise, user-oriented facts and structure them for documentation teams.</description>
56-
<steps>
57-
<step number="1">
58-
<title>Scope and Audience</title>
59-
<actions>
60-
<action>Confirm the feature/aspect and intended audience.</action>
61-
<action>List primary tasks the audience performs with this feature.</action>
62-
</actions>
63-
</step>
64-
<step number="2">
65-
<title>Extract User-Facing Facts</title>
66-
<actions>
67-
<action>Summarize what the feature does and key benefits.</action>
68-
<action>Explain why users need this (jobs-to-be-done, outcomes) and when to use it.</action>
69-
<action>Document step-by-step user workflows and UI interactions.</action>
70-
<action>Capture configuration options that impact user behavior (name, default, effect).</action>
71-
<action>Clarify constraints, limits, and “cannot do” cases with rationale.</action>
72-
<action>Identify common pitfalls and anti-patterns; include “Do/Don’t” guidance.</action>
73-
<action>List common errors with user-facing messages, diagnostics, fixes, and prevention.</action>
74-
<action>Record prerequisites, permissions, and compatibility/version notes.</action>
75-
<action>Flag complex states that warrant visuals (what to show and why), not every step.</action>
76-
</actions>
77-
</step>
78-
<step number="3">
79-
<title>Create Source Material Report</title>
80-
<actions>
81-
<action>Organize findings using user-focused structure (benefits, use cases, how it works, configuration, FAQ, troubleshooting).</action>
82-
<action>Include short code/UI snippets or paths where relevant.</action>
83-
<action>Create `EXTRACTION-[feature].md` with findings.</action>
84-
<action>Highlight items that need visuals (screenshots/diagrams).</action>
85-
</actions>
86-
<output_format>
87-
- Executive summary of the feature/aspect
88-
- Why it matters (goals, value, when to use)
89-
- User workflows and interactions
90-
- Configuration and setup affecting users (with defaults and impact)
91-
- Constraints and limitations (with rationale)
92-
- Common scenarios and troubleshooting playbooks (symptoms → causes → fixes → prevention)
93-
- Do/Don’t and anti‑patterns
94-
- Recommended visuals (what complex states to illustrate and why)
95-
- FAQ and tips
96-
- Version/compatibility notes
97-
</output_format>
98-
</step>
99-
</steps>
100-
</path>
88+
<category name="ui">
89+
<extracts>
90+
<extract>UI components involved</extract>
91+
<extract>User-visible labels and text</extract>
92+
<extract>Interaction patterns</extract>
93+
</extracts>
94+
</category>
10195

102-
<path name="verification">
103-
<title>Verify Documentation Accuracy</title>
104-
<description>Check provided documentation against codebase reality and actual UX.</description>
105-
<steps>
106-
<step number="1">
107-
<title>Analyze Provided Documentation</title>
108-
<actions>
109-
<action>Parse the documentation to identify claims and descriptions.</action>
110-
<action>Extract technical or user-facing specifics mentioned.</action>
111-
<action>Note workflows, configuration, and examples described.</action>
112-
</actions>
113-
</step>
114-
<step number="2">
115-
<title>Verify Against Codebase</title>
116-
<actions>
117-
<action>Check claims against actual implementation and UX.</action>
118-
<action>Verify endpoints/parameters if referenced.</action>
119-
<action>Confirm configuration options and defaults.</action>
120-
<action>Validate code snippets and examples.</action>
121-
<action>Ensure described workflows match implementation.</action>
122-
</actions>
123-
</step>
124-
<step number="3">
125-
<title>Create Verification Report</title>
126-
<actions>
127-
<action>Categorize findings by severity (Critical, Major, Minor).</action>
128-
<action>List inaccuracies with the correct information.</action>
129-
<action>Identify missing important information.</action>
130-
<action>Provide specific corrections and suggestions.</action>
131-
<action>Create `VERIFICATION-[feature].md` with findings.</action>
132-
</actions>
133-
<output_format>
134-
- Verification summary (Accurate/Needs Updates)
135-
- Critical inaccuracies that could mislead users
136-
- Corrections and missing information
137-
- Explanatory gaps (missing “why”, constraints, or decision rationale)
138-
- Troubleshooting coverage gaps (missing symptoms/diagnostics/fixes/prevention)
139-
- Visual recommendations (which complex states warrant screenshots/diagrams)
140-
- Suggestions for clarity improvements
141-
</output_format>
142-
</step>
143-
</steps>
144-
</path>
145-
</workflow_paths>
96+
<category name="integration">
97+
<extracts>
98+
<extract>Other features this interacts with</extract>
99+
<extract>External APIs or services called</extract>
100+
<extract>Events emitted or consumed</extract>
101+
</extracts>
102+
</category>
103+
</fact_categories>
146104

147-
<completion_criteria>
148-
<for_source_material>
149-
<criterion>Audience and scope captured</criterion>
150-
<criterion>User workflows and UI interactions documented</criterion>
151-
<criterion>User-impacting configuration recorded</criterion>
152-
<criterion>Common errors and troubleshooting documented</criterion>
153-
<criterion>Report organized for documentation team use</criterion>
154-
</for_source_material>
155-
<for_verification>
156-
<criterion>All documentation claims verified</criterion>
157-
<criterion>Inaccuracies identified and corrected</criterion>
158-
<criterion>Missing information noted</criterion>
159-
<criterion>Suggestions for improvement provided</criterion>
160-
<criterion>Clear verification report created</criterion>
161-
</for_verification>
162-
</completion_criteria>
105+
<rules>
106+
<rule>Extract facts, not opinions</rule>
107+
<rule>Include source file paths for every fact</rule>
108+
<rule>Use code identifiers and exact strings from source</rule>
109+
<rule>Do NOT paraphrase - quote when possible</rule>
110+
<rule>Do NOT decide what's important - extract everything relevant</rule>
111+
<rule>Do NOT format for end users - output is for docs team</rule>
112+
</rules>
163113
</extraction_workflow>

0 commit comments

Comments
 (0)