scriptoriumadmin/Roo-Code
1
0
Fork 0
mirror of https://github.com/RooVetGit/Roo-Code.git synced 2026-08-28 05:27:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat: improve docs-extractor mode rules for better documentation extraction (#5381)

Browse source 
- 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
This commit is contained in:
Hannes Rudolph 2025-07-03 12:50:09 -06:00 • committed by GitHub
parent a3106bf9a5
commit 2ecf2ce5ad
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 641 additions and 838 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

184
.roo/rules-docs-extractor/1_extraction_workflow.xml
View file

@ -1,30 +1,28 @@
<extraction_workflow>
<mode_overview>
The Docs Extractor mode performs comprehensive analysis of features and components
to generate multi-audience documentation. It extracts technical details, business logic,
user workflows, and all related information to create documentation suitable for
end-users, developers, administrators, and stakeholders.
The Docs Extractor mode analyzes features to generate documentation.
It extracts technical details, business logic, and user workflows
for different audiences.
</mode_overview>
<initialization_phase>
<step number="1">
<title>Understand Documentation Request</title>
<title>Parse Request</title>
<actions>
<action>Parse the user's request to identify the feature or component.</action>
<action>Determine if the user has provided a documentation section for review or is requesting new documentation.</action>
<action>Default to user-friendly documentation unless technical docs are specifically requested.</action>
<action>Focus on practical benefits and real-world usage.</action>
<action>Note any specific aspects the user wants emphasized.</action>
<action>Identify the feature or component in the user's request.</action>
<action>Determine if the request is for a review or to generate new documentation.</action>
<action>Default to user-friendly docs unless technical output is requested.</action>
<action>Note any specific areas to emphasize.</action>
</actions>
<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>
<note>The initial request determines the workflow path (review vs. generation).</note>
</step>
<step number="2">
<title>Initial Feature Discovery</title>
<title>Discover Feature</title>
<actions>
<action>Use semantic search to find all related code</action>
<action>Identify entry points and main components</action>
<action>Map high-level architecture</action>
<action>Find related code with semantic search.</action>
<action>Identify entry points and components.</action>
<action>Map the high-level architecture.</action>
</actions>
<tool_use><![CDATA[
<codebase_search>
@ -36,32 +34,32 @@
<analysis_phases>
<phase name="code_analysis">
<title>Technical Implementation Analysis</title>
<title>Code Analysis</title>
<steps>
<step>
<action>Analyze source code structure</action>
<action>Analyze code structure</action>
<details>
- Identify classes, functions, and modules
- Extract method signatures and parameters
- Document return types and data structures
- Map inheritance and composition relationships
- Identify classes, functions, modules
- Extract method signatures, parameters
- Document return types, data structures
- Map inheritance and composition
</details>
</step>
<step>
<action>Extract API specifications</action>
<action>Extract APIs</action>
<details>
- REST endpoints with methods and parameters
- GraphQL schemas and resolvers
- WebSocket events and handlers
- RPC interfaces and protocols
- REST endpoints
- GraphQL schemas
- WebSocket events
- RPC interfaces
</details>
</step>
<step>
<action>Document configuration options</action>
<action>Document configuration</action>
<details>
- Environment variables
- Configuration files and schemas
- Feature flags and toggles
- Config files and schemas
- Feature flags
- Runtime parameters
</details>
</step>
@ -69,78 +67,78 @@
</phase>
<phase name="business_logic_analysis">
<title>Business Logic and Workflow Extraction</title>
<title>Business Logic Extraction</title>
<steps>
<step>
<action>Map user workflows</action>
<action>Map workflows</action>
<details>
- User journey through the feature
- Decision points and branching logic
- State transitions and lifecycle
- User roles and permissions
- User journey
- Decision points and branching
- State transitions
- Roles and permissions
</details>
</step>
<step>
<action>Document business rules</action>
<details>
- Validation logic and constraints
- Calculation formulas and algorithms
- Validation logic
- Formulas and algorithms
- Business process implementations
- Compliance and regulatory requirements
- Compliance requirements
</details>
</step>
<step>
<action>Identify use cases</action>
<details>
- Primary use cases and scenarios
- Edge cases and special conditions
- Error scenarios and recovery
- Performance considerations
- Primary use cases
- Edge cases
- Error scenarios
- Performance factors
</details>
</step>
</steps>
</phase>
<phase name="integration_analysis">
<title>Dependencies and Integration Analysis</title>
<title>Dependency Analysis</title>
<steps>
<step>
<action>Map external dependencies</action>
<action>Map dependencies</action>
<details>
- Third-party libraries and versions
- Third-party libraries
- External services and APIs
- Database connections and schemas
- Message queues and event systems
- Database connections
- Message queues
</details>
</step>
<step>
<action>Document integration points</action>
<details>
- Incoming webhooks and callbacks
- Incoming webhooks
- Outgoing API calls
- Event publishers and subscribers
- Shared data stores and caches
- Event publishers/subscribers
- Shared data stores
</details>
</step>
<step>
<action>Analyze data flow</action>
<details>
- Input data sources and formats
- Data transformations and mappings
- Data sources and formats
- Data transformations
- Output formats and destinations
- Data retention and lifecycle
- Data retention policies
</details>
</step>
</steps>
</phase>
<phase name="quality_analysis">
<title>Quality and Testing Analysis</title>
<title>Test Analysis</title>
<steps>
<step>
<action>Assess test coverage</action>
<details>
- Unit test coverage and quality
- Unit test coverage
- Integration test scenarios
- End-to-end test flows
- Performance test results
@ -150,7 +148,7 @@
<action>Document error handling</action>
<details>
- Error types and codes
- Exception handling strategies
- Exception handling
- Fallback mechanisms
- Recovery procedures
</details>
@ -158,43 +156,43 @@
<step>
<action>Identify quality metrics</action>
<details>
- Code complexity metrics
- Code complexity
- Performance benchmarks
- Security vulnerability assessments
- Maintainability indices
- Security vulnerabilities
- Maintainability scores
</details>
</step>
</steps>
</phase>
<phase name="security_analysis">
<title>Security and Compliance Analysis</title>
<title>Security Analysis</title>
<steps>
<step>
<action>Document security measures</action>
<action>Document security</action>
<details>
- Authentication mechanisms
- Authorization and access control
- Data encryption methods
- Security headers and policies
- Auth mechanisms
- Access control
- Data encryption
- Security policies
</details>
</step>
<step>
<action>Identify vulnerabilities</action>
<details>
- Known security issues
- Potential attack vectors
- Mitigation strategies
- Security best practices
- Attack vectors
- Mitigation
- Best practices
</details>
</step>
<step>
<action>Compliance requirements</action>
<action>Check compliance</action>
<details>
- Regulatory compliance (GDPR, HIPAA, etc.)
- Industry standards adherence
- Regulatory compliance (GDPR, etc.)
- Industry standards
- Audit trail requirements
- Data privacy considerations
- Data privacy
</details>
</step>
</steps>
@ -202,37 +200,37 @@
</analysis_phases>
<documentation_generation>
<note>This phase has two paths: Reviewing existing docs or Generating new docs. The path taken is determined in the initialization phase.</note>
<note>Workflow branches here: review existing docs or generate new docs.</note>
<step number="1">
<title>Path 1: Review and Recommend Improvements</title>
<note>This path is followed if the user provided a documentation section for review.</note>
<title>Path 1: Review and Recommend</title>
<note>Used when a document is provided for review.</note>
<actions>
<action>Compare the provided documentation against the analysis of the codebase.</action>
<action>Identify inaccuracies (technical, logical), omissions, and areas for improvement.</action>
<action>Categorize inaccuracies by severity (e.g., Critical, Major, Minor, Suggestion).</action>
<action>Formulate a structured recommendation in the chat, suitable for being copied to the docs team.</action>
<action>Do not write any files or make changes yourself.</action>
<action>The final output in the chat should ONLY be the structured recommendation, without any preceding conversational text.</action>
<action>Compare provided docs against codebase analysis.</action>
<action>Identify inaccuracies, omissions, and areas for improvement.</action>
<action>Categorize issues by severity (Critical, Major, Minor).</action>
<action>Formulate a structured recommendation in chat.</action>
<action>Do not write files.</action>
<action>Final output is only the recommendation.</action>
</actions>
</step>
<step number="2">
<title>Path 2: Generate New Documentation</title>
<note>This path is followed if the user requested new documentation.</note>
<title>Path 2: Generate Documentation</title>
<note>Used when new documentation is requested.</note>
<actions>
<action>Choose a documentation style (e.g., user-focused or comprehensive) from `2_documentation_patterns.xml`.</action>
<action>Structure the documentation with clear sections, examples, and user-friendly elements.</action>
<action>Create a `DOCS-TEMP-[feature].md` file with the generated content.</action>
<action>Use a conversational tone and practical examples from `7_user_friendly_examples.xml`.</action>
<action>Select a template from `2_documentation_patterns.xml`.</action>
<action>Structure the document with clear sections and examples.</action>
<action>Create `DOCS-TEMP-[feature].md` with generated content.</action>
<action>Apply tone and examples from `7_user_friendly_examples.xml`.</action>
</actions>
</step>
</documentation_generation>
<completion_criteria>
<criterion>All code paths have been analyzed</criterion>
<criterion>Business logic is fully documented</criterion>
<criterion>Integration points are mapped</criterion>
<criterion>Security considerations are addressed</criterion>
<criterion>Documentation serves all target audiences</criterion>
<criterion>Metadata and cross-references are complete</criterion>
<criterion>Code paths analyzed</criterion>
<criterion>Business logic documented</criterion>
<criterion>Integration points mapped</criterion>
<criterion>Security addressed</criterion>
<criterion>Audience needs met</criterion>
<criterion>Metadata and links are complete</criterion>
</completion_criteria>
</extraction_workflow>

344
.roo/rules-docs-extractor/2_documentation_patterns.xml
View file

@ -1,287 +1,255 @@
<documentation_patterns>
<overview>
Standard patterns and templates for structuring extracted documentation
to serve end-users with clear, practical information.
Standard templates for structuring extracted documentation.
</overview>
<output_structure>
<user_focused_template><![CDATA[
# [Feature Name]
[Brief, clear description of what the feature does and why it matters to users]
[Description of what the feature does and why a user should care.]
### Key Features
- [Feature 1 - written in user-friendly terms]
- [Feature 2 - focus on benefits]
- [Feature 3 - avoid technical jargon]
- [Benefit-oriented feature 1]
- [Benefit-oriented feature 2]
- [Benefit-oriented feature 3]
---
## Why This Matters
## Use Case
[Explain the problem this solves with a real-world example, like:]
**[Before scenario]**: [Description of the old/manual way]
**Before**: [Description of the old way]
- [Pain point 1]
- [Pain point 2]
**[With this feature]**: [Description of the improved experience]
**With this feature]**: [Description of the new experience.]
## How it Works
[Simple explanation of the feature's operation, avoiding implementation details]
[Simple explanation of the feature's operation.]
[Include visual representation if helpful - suggest where diagrams would help]
[Suggest visual representations where helpful.]
---
## Configuration
[User-friendly explanation of settings]
[Explanation of relevant settings.]
1. **[Setting Name]**:
- **Setting**: `[Technical name if needed]`
- **Description**: [What this does in plain language]
- **Default**: [Default value and what it means]
- **Setting**: `[technical_name]`
- **Description**: [What this does.]
- **Default**: [Default value and its meaning.]
2. **[Setting Name]**:
- **Setting**: `[Technical name if needed]`
- **Description**: [What this does in plain language]
- **Default**: [Default value and what it means]
- **Setting**: `[technical_name]`
- **Description**: [What this does.]
- **Default**: [Default value and its meaning.]
---
## Benefits
## FAQ
- **[Benefit 1]**: [Explanation of how this helps]
- **[Benefit 2]**: [Explanation of how this helps]
- **[Benefit 3]**: [Explanation of how this helps]
**"[User question]"**
- [Answer.]
- [Optional tip.]
## Common Questions
**"[User question]"**
- [Answer.]
- [Optional tip.]
**"[Common user question]"**
- [Clear, helpful answer]
- [Additional tips if relevant]
**"[Common user question]"**
- [Clear, helpful answer]
- [Additional tips if relevant]
**"[Common user question]"**
- [Clear, helpful answer]
- [Additional tips if relevant]
## Need Help?
If you run into issues:
1. [First troubleshooting step]
2. [Second troubleshooting step]
3. [Where to get help - e.g., GitHub Issues link]
]]></user_focused_template>
<comprehensive_template><![CDATA[
# [Feature Name] Documentation
# [Feature Name] Technical Documentation
## Table of Contents
1. [Overview](#overview)
2. [Quick Start](#quick-start)
3. [Architecture](#architecture)
4. [API Reference](#api-reference)
5. [Configuration](#configuration)
6. [User Guide](#user-guide)
7. [Developer Guide](#developer-guide)
8. [Administrator Guide](#administrator-guide)
9. [Security](#security)
10. [Performance](#performance)
11. [Troubleshooting](#troubleshooting)
12. [FAQ](#faq)
13. [Changelog](#changelog)
14. [References](#references)
1. Overview
2. Quick Start
3. Architecture
4. API Reference
5. Configuration
6. User Guide
7. Developer Guide
8. Administrator Guide
9. Security
10. Performance
11. Troubleshooting
12. FAQ
13. Changelog
14. References
[Rest of comprehensive template remains available for technical documentation needs]
[This template remains available for generating detailed technical documentation.]
]]></comprehensive_template>
</output_structure>
<user_friendly_patterns>
<before_after_examples>
<documentation_patterns>
<before_after>
<template><![CDATA[
**Previously**: When Roo needed to understand your project, you'd see multiple requests like:
- "Can I read `src/app.js`?" → You approve
- "Now can I read `src/utils.js`?" → You approve
- "And can I read `src/config.json`?" → You approve
**Before**: Multiple, sequential file read requests:
- "Read `src/app.js`?" → Approve
- "Read `src/utils.js`?" → Approve
- "Read `src/config.json`?" → Approve
**Now**: Roo asks once to read all related files together, getting the full picture immediately.
**Now**: One request to read all related files.
]]></template>
</before_after_examples>
</before_after>
<visual_separators>
<use_case>Between major sections</use_case>
<visual_separator>
<format>---</format>
<purpose>Improve readability and scanning</purpose>
</visual_separators>
<purpose>Separate sections.</purpose>
</visual_separator>
<conversational_questions>
<faq>
<template><![CDATA[
## Common Questions
## FAQ
**"Why would I want to disable this feature?"**
- You're using a less capable AI model that works better with single files
- You want more control over which files are accessed
- You're working with very large files that might exceed memory limits
**"Why disable this?"**
- Your AI model handles single files better.
- You need more control over file access.
- You are working with very large files.
**"What happens if some files are blocked?"**
- Roo will read the files you approve and work with those
- Files blocked by `.rooignore` will be automatically excluded
- You can still approve/deny individual files in the batch
**"What if some files are blocked?"**
- Roo reads approved files and works with what it has.
- `.rooignore` files are excluded automatically.
- Individual files can still be denied in the batch dialog.
]]></template>
</conversational_questions>
</faq>
<practical_examples>
<guideline>Show real tool output or interface elements</guideline>
<guideline>Use actual file paths and settings names</guideline>
<guideline>Include common error messages and solutions</guideline>
</practical_examples>
<examples>
<guideline>Show tool output or UI elements.</guideline>
<guideline>Use actual file paths and setting names.</guideline>
<guideline>Include common errors and solutions.</guideline>
</examples>
<benefit_focused_lists>
<template><![CDATA[
## Benefits
- **Faster Results**: Get answers in one step instead of multiple back-and-forth approvals
- **Better Context**: Roo understands relationships between files immediately
- **Less Interruption**: Approve once and let Roo work uninterrupted
]]></template>
</benefit_focused_lists>
<troubleshooting_section>
<troubleshooting>
<template><![CDATA[
## Troubleshooting
**"Roo is asking for too many files at once"**
- Lower the concurrent file limit in settings
- You can still approve or deny individual files in the batch dialog
**"Too many files requested"**
- Lower the concurrent file limit in settings.
- Deny individual files in the batch dialog.
**"The feature isn't working as expected"**
- Check that "Enable concurrent file reads" is turned on in settings
- Verify your concurrent file limit is set appropriately (default: 100)
- Some AI models may not support this feature effectively
**"Feature isn't working"**
- Ensure "Enable concurrent file reads" is on in settings.
- Verify the file limit is set correctly (default: 100).
- Some AI models may not support this feature.
]]></template>
</troubleshooting_section>
</troubleshooting>
<help_section>
<help>
<template><![CDATA[
## Need Help?
## Help
If you run into issues:
1. Check the [FAQ section](/faq) for common solutions
2. Report problems on [GitHub Issues](https://github.com/RooCodeInc/Roo-Code/issues)
3. Include what you were trying to do and any error messages
- See the [FAQ](#faq) for common issues.
- Report problems on [GitHub Issues](https://github.com/RooCodeInc/Roo-Code/issues).
- Include reproduction steps and error messages.
]]></template>
</help_section>
</user_friendly_patterns>
</help>
</documentation_patterns>
<audience_specific_sections>
<audience type="end_users">
<focus_areas>
<area>Step-by-step tutorials with screenshots</area>
<area>Common use case examples</area>
<area>Troubleshooting guides for user errors</area>
<area>Feature benefits and value propositions</area>
</focus_areas>
<writing_style>
<guideline>Use simple, non-technical language</guideline>
<guideline>Include visual aids and examples</guideline>
<guideline>Focus on outcomes rather than implementation</guideline>
<guideline>Provide clear action steps</guideline>
</writing_style>
<audience_sections>
<audience type="end_user">
<focus>
<area>Tutorials</area>
<area>Use cases</area>
<area>Troubleshooting</area>
<area>Benefits</area>
</focus>
<style>
<guideline>Simple language</guideline>
<guideline>Visual aids</guideline>
<guideline>Focus on outcomes</guideline>
<guideline>Clear action steps</guideline>
</style>
</audience>
<audience type="developers">
<focus_areas>
<area>Code examples and snippets</area>
<area>API specifications and contracts</area>
<area>Integration patterns and best practices</area>
<area>Performance optimization techniques</area>
</focus_areas>
<writing_style>
<guideline>Use precise technical terminology</guideline>
<guideline>Include code samples in multiple languages</guideline>
<guideline>Document edge cases and limitations</guideline>
<guideline>Provide debugging and testing guidance</guideline>
</writing_style>
<audience type="developer">
<focus>
<area>Code examples</area>
<area>API specs</area>
<area>Integration patterns</area>
<area>Performance</area>
</focus>
<style>
<guideline>Precise terminology</guideline>
<guideline>Code samples</guideline>
<guideline>Document edge cases</guideline>
<guideline>Debugging guidance</guideline>
</style>
</audience>
<audience type="administrators">
<focus_areas>
<area>Deployment and configuration procedures</area>
<area>Monitoring and maintenance tasks</area>
<area>Security hardening guidelines</area>
<area>Backup and disaster recovery</area>
</focus_areas>
<writing_style>
<guideline>Focus on operational aspects</guideline>
<guideline>Include command-line examples</guideline>
<guideline>Document automation opportunities</guideline>
<guideline>Emphasize security and compliance</guideline>
</writing_style>
<audience type="administrator">
<focus>
<area>Deployment</area>
<area>Monitoring</area>
<area>Security hardening</area>
<area>Backup and recovery</area>
</focus>
<style>
<guideline>Operational focus</guideline>
<guideline>CLI examples</guideline>
<guideline>Automation opportunities</guideline>
<guideline>Security and compliance</guideline>
</style>
</audience>
<audience type="stakeholders">
<focus_areas>
<area>Business value and ROI</area>
<area>Feature capabilities and limitations</area>
<audience type="stakeholder">
<focus>
<area>Business value</area>
<area>Capabilities and limits</area>
<area>Competitive advantages</area>
<area>Risk assessment and mitigation</area>
</focus_areas>
<writing_style>
<guideline>Use business-oriented language</guideline>
<guideline>Include metrics and KPIs</guideline>
<guideline>Focus on strategic benefits</guideline>
<guideline>Provide executive summaries</guideline>
</writing_style>
<area>Risk assessment</area>
</focus>
<style>
<guideline>Business language</guideline>
<guideline>Metrics and KPIs</guideline>
<guideline>Strategic benefits</guideline>
<guideline>Executive summaries</guideline>
</style>
</audience>
</audience_specific_sections>
</audience_sections>
<metadata_patterns>
<version_info>
<template><![CDATA[
### Version Compatibility Matrix
| Component | Min Version | Recommended | Max Version | Notes |
|-----------|-------------|-------------|-------------|-------|
### Version Compatibility
| Component | Min | Recommended | Max | Notes |
|-----------|-----|-------------|-----|-------|
| [Component] | [version] | [version] | [version] | [notes] |
]]></template>
</version_info>
<deprecation_notice>
<template><![CDATA[
> ⚠️ **Deprecation Notice**
>
> This feature/method is deprecated as of version [X.Y.Z].
> - **Deprecated**: [date]
> - **Removal Target**: [version/date]
> - **Migration Path**: [See migration guide](#migration)
> - **Replacement**: [new feature/method]
> ⚠️ **Deprecated**
>
> Deprecated since: [vX.Y.Z] on [date]
> Removal target: [vA.B.C]
> Migration: See [migration guide](#migration).
> Replacement: [new feature/method].
]]></template>
</deprecation_notice>
<security_warning>
<template><![CDATA[
> 🔒 **Security Consideration**
>
> [Description of security concern]
> - **Risk Level**: [High/Medium/Low]
> - **Affected Versions**: [versions]
> - **Mitigation**: [steps to address]
> - **References**: [CVE/advisory links]
> 🔒 **Security Warning**
>
> [Description of concern]
> - **Risk**: [High/Medium/Low]
> - **Affected**: [versions]
> - **Mitigation**: [steps]
> - **References**: [links]
]]></template>
</security_warning>
<performance_note>
<template><![CDATA[
> ⚡ **Performance Impact**
>
> ⚡ **Performance Note**
>
> [Description of performance consideration]
> - **Impact**: [metrics/benchmarks]
> - **Optimization**: [recommended approach]
> - **Impact**: [metrics]
> - **Optimization**: [approach]
> - **Trade-offs**: [considerations]
]]></template>
</performance_note>

206
.roo/rules-docs-extractor/3_analysis_techniques.xml
View file

@ -1,19 +1,18 @@
<analysis_techniques>
<overview>
Comprehensive techniques for analyzing code and extracting documentation-worthy
information from various aspects of a codebase.
Techniques for analyzing code to extract documentation.
</overview>
<code_analysis_techniques>
<technique name="entry_point_analysis">
<description>
Identify and analyze main entry points to understand feature flow
Analyze entry points to understand feature flow.
</description>
<steps>
<step>Search for main functions, controllers, or route handlers</step>
<step>Trace execution flow from entry to exit</step>
<step>Map decision branches and conditionals</step>
<step>Document input validation and preprocessing</step>
<step>Find main functions, controllers, or route handlers.</step>
<step>Trace execution flow.</step>
<step>Map decision branches.</step>
<step>Document input validation.</step>
</steps>
<tools><![CDATA[
<!-- Find entry points -->
@ -36,7 +35,7 @@
<technique name="api_extraction">
<description>
Extract API specifications from code implementations
Extract API specifications from code.
</description>
<patterns>
<pattern type="rest">
@ -46,10 +45,8 @@
<extraction>
- HTTP method
- Route path
- Path parameters
- Query parameters
- Request body schema
- Response schemas
- Path/query parameters
- Request/response schemas
- Status codes
</extraction>
</pattern>
@ -58,9 +55,8 @@
type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
]]></search_regex>
<extraction>
- Schema types
- Schema and input types
- Resolvers
- Input types
- Return types
- Field arguments
</extraction>
@ -70,15 +66,15 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
<technique name="dependency_mapping">
<description>
Map all dependencies and integration points
Map dependencies and integration points.
</description>
<analysis_points>
<point>Import statements and require calls</point>
<point>Package.json dependencies</point>
<point>Import/require statements</point>
<point>package.json dependencies</point>
<point>External API calls</point>
<point>Database connections</point>
<point>DB connections</point>
<point>Message queue integrations</point>
<point>File system operations</point>
<point>Filesystem operations</point>
</analysis_points>
<tools><![CDATA[
<!-- Find all imports -->
@ -102,31 +98,22 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
<technique name="data_model_extraction">
<description>
Extract data models, schemas, and type definitions
Extract data models, schemas, and type definitions.
</description>
<sources>
<source type="typescript">
<patterns>
- interface definitions
- type aliases
- class declarations
- enum definitions
- interfaces, types, classes, enums
</patterns>
</source>
<source type="database">
<patterns>
- Schema definitions
- Migration files
- Model definitions (ORM)
- SQL CREATE statements
- Schema definitions, migration files, ORM models
</patterns>
</source>
<source type="validation">
<patterns>
- JSON Schema
- Joi/Yup schemas
- Validation decorators
- Custom validators
- JSON Schema, Joi/Yup/Zod schemas, validation decorators
</patterns>
</source>
</sources>
@ -147,37 +134,33 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
<technique name="business_logic_extraction">
<description>
Identify and document business rules and logic
Identify and document business rules.
</description>
<indicators>
<indicator>Complex conditional statements</indicator>
<indicator>Complex conditionals</indicator>
<indicator>Calculation functions</indicator>
<indicator>Validation rules</indicator>
<indicator>State machines</indicator>
<indicator>Business-specific constants</indicator>
<indicator>Domain-specific algorithms</indicator>
<indicator>Domain-specific constants and algorithms</indicator>
</indicators>
<documentation_focus>
<focus>Why the logic exists (business requirement)</focus>
<focus>When the logic applies (conditions)</focus>
<focus>What the logic does (transformation)</focus>
<focus>Edge cases and exceptions</focus>
<focus>Business impact of changes</focus>
<focus>Why logic exists (business need)</focus>
<focus>When logic applies (conditions)</focus>
<focus>What logic does (transformation)</focus>
<focus>Edge cases</focus>
<focus>Impact of changes</focus>
</documentation_focus>
</technique>
<technique name="error_handling_analysis">
<description>
Document error handling strategies and recovery mechanisms
Document error handling and recovery.
</description>
<analysis_areas>
<area>Try-catch blocks and error boundaries</area>
<area>Custom error classes and types</area>
<area>try/catch blocks, error boundaries</area>
<area>Custom error classes</area>
<area>Error codes and messages</area>
<area>Logging strategies</area>
<area>Fallback mechanisms</area>
<area>Retry logic</area>
<area>Circuit breakers</area>
<area>Logging, fallbacks, retries, circuit breakers</area>
</analysis_areas>
<search_patterns><![CDATA[
<!-- Find error handling -->
@ -196,81 +179,68 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
<technique name="security_analysis">
<description>
Identify security measures and potential vulnerabilities
Identify security measures and vulnerabilities.
</description>
<security_checks>
<check category="authentication">
<patterns>
- JWT implementation
- Session management
- OAuth flows
- API key handling
- JWT, sessions, OAuth, API keys
</patterns>
</check>
<check category="authorization">
<patterns>
- Role-based access control
- Permission checks
- Resource ownership validation
- Access control lists
- RBAC, permission checks, ownership validation
</patterns>
</check>
<check category="data_protection">
<patterns>
- Encryption usage
- Hashing algorithms
- Sensitive data handling
- PII protection
- Encryption, hashing, sensitive data handling
</patterns>
</check>
<check category="input_validation">
<patterns>
- Input sanitization
- SQL injection prevention
- XSS protection
- CSRF tokens
</patterns>
- Sanitization, SQLi/XSS/CSRF prevention
</parents>
</check>
</security_checks>
</technique>
<technique name="performance_analysis">
<description>
Identify performance characteristics and optimization opportunities
Identify performance factors and optimization opportunities.
</description>
<analysis_points>
<point>Database query patterns (N+1 queries)</point>
<point>DB query patterns (N+1)</point>
<point>Caching strategies</point>
<point>Async/await usage</point>
<point>Async usage</point>
<point>Batch processing</point>
<point>Resource pooling</point>
<point>Memory management</point>
<point>Algorithm complexity</point>
</analysis_points>
<metrics_to_document>
<metric>Time complexity of algorithms</metric>
<metric>Space complexity</metric>
<metric>Database query counts</metric>
<metric>Time/space complexity</metric>
<metric>DB query counts</metric>
<metric>API response times</metric>
<metric>Memory usage patterns</metric>
<metric>Concurrent request handling</metric>
<metric>Memory usage</metric>
<metric>Concurrency handling</metric>
</metrics_to_document>
</technique>
<technique name="test_coverage_analysis">
<description>
Analyze test coverage and quality
Analyze test coverage.
</description>
<test_types>
<type name="unit_tests">
<type name="unit">
<location>__tests__, *.test.ts, *.spec.ts</location>
<analysis>Function-level coverage</analysis>
<analysis>Function coverage</analysis>
</type>
<type name="integration_tests">
<type name="integration">
<location>integration/, e2e/</location>
<analysis>Feature workflow coverage</analysis>
<analysis>Workflow coverage</analysis>
</type>
<type name="api_tests">
<type name="api">
<location>api-tests/, *.api.test.ts</location>
<analysis>Endpoint coverage</analysis>
</type>
@ -293,20 +263,16 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
<technique name="configuration_extraction">
<description>
Extract all configuration options and their impacts
Extract configuration options and their impacts.
</description>
<configuration_sources>
<source>Environment variables (.env files)</source>
<source>Configuration files (config.json, settings.yml)</source>
<source>Command-line arguments</source>
<source>Feature flags</source>
<source>Build-time constants</source>
<source>.env files, config files, CLI args, feature flags</source>
</configuration_sources>
<documentation_requirements>
<requirement>Default values</requirement>
<requirement>Valid value ranges</requirement>
<requirement>Impact on behavior</requirement>
<requirement>Dependencies between configs</requirement>
<requirement>Valid values</requirement>
<requirement>Behavior impact</requirement>
<requirement>Config dependencies</requirement>
<requirement>Security implications</requirement>
</documentation_requirements>
</technique>
@ -315,40 +281,29 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
<workflow_analysis>
<technique name="user_journey_mapping">
<description>
Map complete user workflows through the feature
Map user workflows through the feature.
</description>
<steps>
<step>Identify user entry points (UI, API, CLI)</step>
<step>Trace user actions through the system</step>
<step>Document decision points and branches</step>
<step>Map data transformations at each step</step>
<step>Identify exit points and outcomes</step>
<step>Identify entry points (UI, API, CLI).</step>
<step>Trace user actions.</step>
<step>Document decision points.</step>
<step>Map data transformations.</step>
<step>Identify outcomes.</step>
</steps>
<deliverables>
<deliverable>User flow diagrams</deliverable>
<deliverable>Step-by-step procedures</deliverable>
<deliverable>Decision trees</deliverable>
<deliverable>State transition diagrams</deliverable>
<deliverable>Flow diagrams, procedures, decision trees, state diagrams.</deliverable>
</deliverables>
</technique>
<technique name="integration_flow_analysis">
<description>
Document how the feature integrates with other systems
Document integration with other systems.
</description>
<integration_types>
<type>Synchronous API calls</type>
<type>Asynchronous messaging</type>
<type>Event-driven interactions</type>
<type>Batch processing</type>
<type>Real-time streaming</type>
<type>Sync API calls, async messaging, events, batch processing, streaming.</type>
</integration_types>
<documentation_focus>
<focus>Integration protocols and formats</focus>
<focus>Authentication mechanisms</focus>
<focus>Error handling and retries</focus>
<focus>Data transformation requirements</focus>
<focus>SLA and performance expectations</focus>
<focus>Protocols, auth, error handling, data transforms, SLAs.</focus>
</documentation_focus>
</technique>
</workflow_analysis>
@ -356,10 +311,7 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
<metadata_extraction>
<technique name="version_compatibility">
<sources>
<source>Package.json engines field</source>
<source>README compatibility sections</source>
<source>Migration guides</source>
<source>Breaking change documentation</source>
<source>package.json, READMEs, migration guides, breaking changes docs.</source>
</sources>
<extraction_pattern><![CDATA[
<!-- Find version requirements -->
@ -372,16 +324,10 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
<technique name="deprecation_tracking">
<indicators>
<indicator>@deprecated annotations</indicator>
<indicator>TODO: deprecate comments</indicator>
<indicator>Legacy code markers</indicator>
<indicator>Migration warnings</indicator>
<indicator>@deprecated, TODO comments, legacy code markers.</indicator>
</indicators>
<documentation_requirements>
<requirement>Deprecation date</requirement>
<requirement>Removal timeline</requirement>
<requirement>Migration path</requirement>
<requirement>Alternative solutions</requirement>
<requirement>Deprecation date, removal timeline, migration path, alternatives.</requirement>
</documentation_requirements>
</technique>
</metadata_extraction>
@ -389,21 +335,17 @@ type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
<quality_indicators>
<indicator name="documentation_completeness">
<checks>
<check>All public APIs documented</check>
<check>Examples provided for complex features</check>
<check>Error scenarios covered</check>
<check>Configuration options explained</check>
<check>Security considerations addressed</check>
<check>Public APIs documented.</check>
<check>Examples for complex features.</check>
<check>Error scenarios covered.</check>
<check>Config options explained.</check>
<check>Security addressed.</check>
</checks>
</indicator>
<indicator name="code_quality_metrics">
<metrics>
<metric>Cyclomatic complexity</metric>
<metric>Code duplication</metric>
<metric>Test coverage percentage</metric>
<metric>Documentation coverage</metric>
<metric>Technical debt indicators</metric>
<metric>Cyclomatic complexity, code duplication, test coverage, doc coverage, tech debt.</metric>
</metrics>
</indicator>
</quality_indicators>

166
.roo/rules-docs-extractor/4_tool_usage_guide.xml
View file

@ -1,16 +1,15 @@
<tool_usage_guide>
<overview>
Specific guidance on using tools effectively for comprehensive documentation extraction,
with emphasis on gathering complete information across all aspects of a feature.
Guidance on using tools for documentation extraction.
</overview>
<tool_sequence>
<priority level="1">
<tool>codebase_search</tool>
<purpose>Initial discovery of feature-related code</purpose>
<purpose>Initial code discovery.</purpose>
<usage_patterns>
<pattern>
<scenario>Finding feature entry points</scenario>
<scenario>Find feature entry points</scenario>
<example><![CDATA[
<codebase_search>
<query>authentication login user session JWT token</query>
@ -18,7 +17,7 @@
]]></example>
</pattern>
<pattern>
<scenario>Locating business logic</scenario>
<scenario>Find business logic</scenario>
<example><![CDATA[
<codebase_search>
<query>calculate pricing discount tax invoice billing</query>
@ -26,7 +25,7 @@
]]></example>
</pattern>
<pattern>
<scenario>Finding configuration</scenario>
<scenario>Find configuration</scenario>
<example><![CDATA[
<codebase_search>
<query>config settings environment variables .env process.env</query>
@ -38,11 +37,11 @@
<priority level="2">
<tool>list_code_definition_names</tool>
<purpose>Understanding code structure and organization</purpose>
<purpose>Understand code structure.</purpose>
<best_practices>
<practice>Use on directories containing core feature logic</practice>
<practice>Analyze both implementation and test directories</practice>
<practice>Look for patterns in naming conventions</practice>
<practice>Use on core feature directories.</practice>
<practice>Analyze implementation and test directories.</practice>
<practice>Look for naming patterns.</practice>
</best_practices>
<example><![CDATA[
<list_code_definition_names>
@ -53,12 +52,12 @@
<priority level="3">
<tool>read_file</tool>
<purpose>Deep analysis of specific implementations</purpose>
<purpose>Analyze specific implementations.</purpose>
<strategy>
<step>Read main feature files first</step>
<step>Follow imports to understand dependencies</step>
<step>Read test files to understand expected behavior</step>
<step>Examine configuration and type definition files</step>
<step>Read main feature files.</step>
<step>Follow imports to find dependencies.</step>
<step>Read test files for expected behavior.</step>
<step>Examine config and type definition files.</step>
</strategy>
<batch_reading><![CDATA[
<read_file>
@ -85,10 +84,10 @@
<priority level="4">
<tool>search_files</tool>
<purpose>Finding specific patterns and implementations</purpose>
<purpose>Find specific patterns.</purpose>
<use_cases>
<use_case>
<description>Find all API endpoints</description>
<description>Find API endpoints</description>
<example><![CDATA[
<search_files>
<path>src</path>
@ -97,7 +96,7 @@
]]></example>
</use_case>
<use_case>
<description>Find error handling patterns</description>
<description>Find error handling</description>
<example><![CDATA[
<search_files>
<path>src</path>
@ -106,7 +105,7 @@
]]></example>
</use_case>
<use_case>
<description>Find configuration usage</description>
<description>Find config usage</description>
<example><![CDATA[
<search_files>
<path>src</path>
@ -120,14 +119,14 @@
<documentation_generation_tools>
<tool name="write_to_file">
<purpose>Create the final documentation file when generating new documentation from scratch.</purpose>
<note>This tool is NOT used when reviewing a user-provided document section. In that scenario, feedback is provided directly in the chat.</note>
<purpose>Create documentation file for new docs.</purpose>
<note>Not used for reviews. Feedback for reviews is provided in chat.</note>
<file_naming>DOCS-TEMP-[feature-name].md</file_naming>
<best_practices>
<practice>Use descriptive feature names in filename</practice>
<practice>Include table of contents with anchors</practice>
<practice>Use consistent markdown formatting</practice>
<practice>Include code examples with syntax highlighting</practice>
<practice>Use descriptive feature name in filename.</practice>
<practice>Include table of contents.</practice>
<practice>Use consistent Markdown formatting.</practice>
<practice>Include syntax-highlighted code examples.</practice>
</best_practices>
<example><![CDATA[
<write_to_file>
@ -149,32 +148,32 @@ The authentication system provides secure user authentication using JWT tokens..
</tool>
<tool name="ask_followup_question">
<purpose>Clarify requirements when multiple interpretations exist</purpose>
<purpose>Clarify ambiguous requirements.</purpose>
<when_to_use>
<scenario>Multiple features with similar names exist</scenario>
<scenario>Documentation depth needs clarification</scenario>
<scenario>Target audience priorities need definition</scenario>
<scenario>Multiple features have similar names.</scenario>
<scenario>Documentation depth is unclear.</scenario>
<scenario>Audience priorities are undefined.</scenario>
</when_to_use>
<examples>
<example><![CDATA[
<ask_followup_question>
<question>Which aspects of the authentication system should I focus on?</question>
<question>Which authentication aspects should be the focus?</question>
<follow_up>
<suggest>Complete authentication flow including JWT tokens, session management, and OAuth integration</suggest>
<suggest>Only the JWT token implementation and validation</suggest>
<suggest>OAuth2 integration with external providers</suggest>
<suggest>Password reset and account recovery workflows</suggest>
<suggest>The complete flow (JWT, sessions, OAuth).</suggest>
<suggest>Only JWT implementation and validation.</suggest>
<suggest>Only OAuth2 integration.</suggest>
<suggest>Password reset and recovery workflows.</suggest>
</follow_up>
</ask_followup_question>
]]></example>
<example><![CDATA[
<ask_followup_question>
<question>What level of technical detail should the documentation include?</question>
<question>What level of technical detail is needed?</question>
<follow_up>
<suggest>High-level overview suitable for all audiences</suggest>
<suggest>Detailed technical implementation for developers</suggest>
<suggest>API reference with code examples</suggest>
<suggest>Complete coverage for all audience types</suggest>
<suggest>High-level overview for all audiences.</suggest>
<suggest>Detailed developer implementation.</suggest>
<suggest>API reference with code examples.</suggest>
<suggest>Full coverage for all audiences.</suggest>
</follow_up>
</ask_followup_question>
]]></example>
@ -183,21 +182,21 @@ The authentication system provides secure user authentication using JWT tokens..
</documentation_generation_tools>
<analysis_strategies>
<strategy name="comprehensive_file_discovery">
<strategy name="file_discovery">
<description>
Systematic approach to finding all files related to a feature
Find all files related to a feature.
</description>
<steps>
<step>
<action>Start with semantic search</action>
<action>Start with semantic search.</action>
<tool_use><![CDATA[
<codebase_search>
<query>feature implementation main logic core functionality</query>
<query>feature implementation main logic</query>
</codebase_search>
]]></tool_use>
</step>
<step>
<action>List directory structure</action>
<action>List directory structure.</action>
<tool_use><![CDATA[
<list_files>
<path>src/features</path>
@ -206,7 +205,7 @@ The authentication system provides secure user authentication using JWT tokens..
]]></tool_use>
</step>
<step>
<action>Find related tests</action>
<action>Find related tests.</action>
<tool_use><![CDATA[
<search_files>
<path>src</path>
@ -216,7 +215,7 @@ The authentication system provides secure user authentication using JWT tokens..
]]></tool_use>
</step>
<step>
<action>Locate configuration files</action>
<action>Find config files.</action>
<tool_use><![CDATA[
<search_files>
<path>.</path>
@ -230,14 +229,14 @@ The authentication system provides secure user authentication using JWT tokens..
<strategy name="dependency_chain_analysis">
<description>
Follow import chains to understand all dependencies
Follow import chains to map dependencies.
</description>
<process>
<step>Read main feature file</step>
<step>Extract all imports</step>
<step>Read each imported file</step>
<step>Recursively analyze their imports</step>
<step>Build dependency graph</step>
<step>Read main file.</step>
<step>Extract all imports.</step>
<step>Read each imported file.</step>
<step>Recursively analyze imports.</step>
<step>Build dependency graph.</step>
</process>
<import_patterns><![CDATA[
<!-- TypeScript/JavaScript imports -->
@ -256,35 +255,31 @@ The authentication system provides secure user authentication using JWT tokens..
<strategy name="api_documentation_extraction">
<description>
Extract complete API documentation from code
Extract API documentation from code.
</description>
<extraction_points>
<point>Route definitions</point>
<point>Request/response schemas</point>
<point>Authentication requirements</point>
<point>Rate limiting rules</point>
<point>Error responses</point>
<point>Route definitions, request/response schemas, auth requirements, rate limiting, error responses.</point>
</extraction_points>
<tools_sequence>
<sequence>
<step>Find all route files</step>
<step>Extract route definitions</step>
<step>Find associated controllers</step>
<step>Analyze request validation</step>
<step>Document response formats</step>
<step>Find route files.</step>
<step>Extract route definitions.</step>
<step>Find controllers.</step>
<step>Analyze request validation.</step>
<step>Document response formats.</step>
</sequence>
</tools_sequence>
</strategy>
<strategy name="test_driven_documentation">
<description>
Use tests to understand expected behavior
Use tests to document expected behavior.
</description>
<benefits>
<benefit>Tests show real usage examples</benefit>
<benefit>Test descriptions explain functionality</benefit>
<benefit>Edge cases are often tested</benefit>
<benefit>Expected outputs are documented</benefit>
<benefit>Tests provide usage examples.</benefit>
<benefit>Test descriptions explain functionality.</benefit>
<benefit>Tests cover edge cases.</benefit>
<benefit>Tests document expected outputs.</benefit>
</benefits>
<extraction_approach><![CDATA[
<!-- Find test descriptions -->
@ -354,44 +349,31 @@ config\.(\w+)\.(\w+)
</common_patterns>
<output_optimization>
<guideline name="structured_sections">
<description>Organize output for easy navigation</description>
<guideline name="structure">
<description>Organize output for navigation.</description>
<structure>
- Clear hierarchy with numbered sections
- Consistent heading levels
- Table of contents with links
- Cross-references between sections
- Clear hierarchy, consistent headings, ToC with links, cross-references.
</structure>
</guideline>
<guideline name="code_examples">
<description>Include relevant code examples</description>
<description>Include relevant code examples.</description>
<best_practices>
- Use syntax highlighting
- Show both request and response
- Include error cases
- Provide language-specific examples
- Use syntax highlighting, show request/response, include error cases.
</best_practices>
</guideline>
<guideline name="visual_aids">
<description>Suggest where diagrams would help</description>
<guideline name="visuals">
<description>Suggest diagrams where helpful.</description>
<diagram_types>
- Architecture diagrams
- Sequence diagrams
- Data flow diagrams
- State machines
- Architecture, sequence, data flow, state machine diagrams.
</diagram_types>
</guideline>
<guideline name="metadata_inclusion">
<description>Always include important metadata</description>
<guideline name="metadata">
<description>Include important metadata.</description>
<required_metadata>
- Version compatibility
- Last updated date
- Feature status (stable/beta/deprecated)
- Performance characteristics
- Security considerations
- Version compatibility, last updated, status, performance, security.
</required_metadata>
</guideline>
</output_optimization>

55
.roo/rules-docs-extractor/5_complete_extraction_examples.xml
View file

@ -1,48 +1,42 @@
<complete_extraction_examples>
<overview>
Complete examples demonstrating the full documentation extraction workflow
for different types of features and components.
Examples of the documentation extraction workflow.
</overview>
<example name="authentication_system_extraction">
<scenario>
Extract comprehensive documentation for a JWT-based authentication system
including login, logout, token refresh, and role-based access control.
Extract documentation for a JWT-based authentication system, including login, token refresh, and RBAC.
</scenario>
<workflow>
<step number="1">
<description>Initial feature discovery</description>
<description>Discover feature</description>
<tool_use><![CDATA[
<codebase_search>
<query>authentication JWT login logout token refresh auth middleware</query>
</codebase_search>
]]></tool_use>
<expected_findings>
- Auth controller files
- JWT service implementations
- Middleware functions
- User model with auth fields
- Auth route definitions
- Auth controllers, services, middleware, models, and routes.
</expected_findings>
</step>
<step number="2">
<description>Analyze authentication structure</description>
<description>Analyze structure</description>
<tool_use><![CDATA[
<list_code_definition_names>
<path>src/auth</path>
</list_code_definition_names>
]]></tool_use>
<analysis>
- Identify main classes and functions
- Map authentication flow
- Find token generation/validation logic
- Identify main classes/functions.
- Map auth flow.
- Find token generation/validation logic.
</analysis>
</step>
<step number="3">
<description>Read core implementation files</description>
<description>Read core files</description>
<tool_use><![CDATA[
<read_file>
<args>
@ -75,16 +69,12 @@
</search_files>
]]></tool_use>
<findings>
- POST /auth/login
- POST /auth/logout
- POST /auth/refresh
- GET /auth/profile
- POST /auth/register
- POST /auth/login, POST /auth/logout, POST /auth/refresh, GET /auth/profile, POST /auth/register
</findings>
</step>
<step number="5">
<description>Document configuration</description>
<description>Extract configuration</description>
<tool_use><![CDATA[
<search_files>
<path>src</path>
@ -94,7 +84,7 @@
</step>
<step number="6">
<description>Analyze security measures</description>
<description>Analyze security</description>
<tool_use><![CDATA[
<search_files>
<path>src/auth</path>
@ -104,7 +94,7 @@
</step>
<step number="7">
<description>Generate documentation</description>
<description>Generate docs</description>
<tool_use><![CDATA[
<write_to_file>
<path>DOCS-TEMP-authentication-system.md</path>
@ -552,24 +542,23 @@ DEBUG=auth:* npm start
</workflow>
<key_takeaways>
<takeaway>Start with semantic search to find all related files</takeaway>
<takeaway>Read multiple files together for context</takeaway>
<takeaway>Extract API documentation from route definitions</takeaway>
<takeaway>Use tests to understand expected behavior</takeaway>
<takeaway>Document security measures comprehensively</takeaway>
<takeaway>Include troubleshooting based on common errors</takeaway>
<takeaway>Use semantic search to find related files.</takeaway>
<takeaway>Read multiple files for context.</takeaway>
<takeaway>Extract API docs from route definitions.</takeaway>
<takeaway>Use tests to understand behavior.</takeaway>
<takeaway>Document security measures.</takeaway>
<takeaway>Include troubleshooting for common errors.</takeaway>
</key_takeaways>
</example>
<example name="database_schema_extraction">
<scenario>
Extract documentation for database models, relationships, migrations,
and data access patterns.
Extract documentation for database models, relationships, and migrations.
</scenario>
<workflow>
<step number="1">
<description>Find database-related files</description>
<description>Find DB files</description>
<tool_use><![CDATA[
<codebase_search>
<query>database schema model entity migration table column relationship</query>
@ -578,7 +567,7 @@ DEBUG=auth:* npm start
</step>
<step number="2">
<description>Analyze model definitions</description>
<description>Analyze models</description>
<tool_use><![CDATA[
<search_files>
<path>src/models</path>

272
.roo/rules-docs-extractor/6_communication_guidelines.xml
View file

@ -1,90 +1,87 @@
<communication_guidelines>
<overview>
Guidelines for communicating with users and formatting documentation output
during the extraction process.
Guidelines for user communication and output formatting.
</overview>
<user_interaction>
<initial_understanding>
<principle>Users will specify what they want documented in their initial message</principle>
<principle>Start working immediately based on their request</principle>
<principle>Only ask for clarification if genuinely ambiguous</principle>
</initial_understanding>
<initial_contact>
<principle>Act on the user's request immediately.</principle>
<principle>Only ask for clarification if the request is ambiguous.</principle>
</initial_contact>
<clarification_only_when_needed>
<clarification>
<when_to_ask>
<scenario>Multiple features with identical names found</scenario>
<scenario>Request is genuinely ambiguous (rare)</scenario>
<scenario>User explicitly asks for options</scenario>
<scenario>Multiple features with similar names are found.</scenario>
<scenario>The request is ambiguous.</scenario>
<scenario>The user explicitly asks for options.</scenario>
</when_to_ask>
<question_example><![CDATA[
<ask_followup_question>
<question>I found multiple authentication systems. Which one should I document?</question>
<question>Found multiple auth systems. Which to document?</question>
<follow_up>
<suggest>JWT-based authentication system (src/auth/jwt/*)</suggest>
<suggest>JWT-based system (src/auth/jwt/*)</suggest>
<suggest>OAuth2 integration (src/auth/oauth/*)</suggest>
<suggest>Basic authentication middleware (src/middleware/basic-auth.ts)</suggest>
<suggest>All authentication features comprehensively</suggest>
<suggest>Basic auth middleware (src/middleware/basic-auth.ts)</suggest>
<suggest>All of them</suggest>
</follow_up>
</ask_followup_question>
]]></question_example>
</clarification_only_when_needed>
</clarification>
<progress_updates>
<when_to_update>
<trigger>Starting major analysis phase</trigger>
<trigger>Completed significant extraction</trigger>
<trigger>Found unexpected complexity</trigger>
<trigger>Discovered related features</trigger>
<trigger>Starting a major analysis phase.</trigger>
<trigger>Extraction is complete.</trigger>
<trigger>Unexpected complexity is found.</trigger>
</when_to_update>
<update_format>
<template>
Analyzing [component/feature]...
- Found [X] files related to [feature]
- Identified [Y] API endpoints
- Discovered [Z] configuration options
Analyzing [component]...
- Found [X] related files.
- Identified [Y] API endpoints.
- Found [Z] config options.
</template>
</update_format>
</progress_updates>
<findings_communication>
<important_discoveries>
<important_findings>
<discovery type="security_issue">
Alert user to potential security concerns found during analysis
Alert user to security concerns found during analysis.
</discovery>
<discovery type="deprecated_code">
Note deprecated features that need migration documentation
Note deprecated features needing migration docs.
</discovery>
<discovery type="missing_documentation">
Highlight areas where code lacks inline documentation
<discovery type="missing_docs">
Highlight code that lacks inline documentation.
</discovery>
<discovery type="complex_dependencies">
Warn about intricate dependency chains affecting the feature
Warn about complex dependency chains.
</discovery>
</important_discoveries>
</important_findings>
<review_findings>
<template><![CDATA[
I have reviewed the documentation section provided. Here are my recommendations for improvement:
Review of the provided documentation section is complete.
**Overall Assessment**: [Brief summary of the document's quality]
**Assessment**: [Summary of document quality]
**Recommendations for Improvement**:
**Recommendations**:
* **Critical Inaccuracies**:
* [Inaccuracy 1]: The documentation states [X], but the code implements [Y].
* [Inaccuracy 2]: ...
* [Inaccuracy 1]: Docs state [X], but code implements [Y].
* ...
* **Major Omissions**:
* The documentation is missing information about [Missing Feature/Concept].
* ...
* **Omissions**:
* Missing info about [Missing Feature].
* ...
* **Suggestions for Clarity**:
* The section on [Topic] could be clarified by [Suggestion].
* ...
* **Clarity Suggestions**:
* The section on [Topic] can be clarified by [Suggestion].
* ...
This feedback can be copied and pasted for your documentation team.
Copy this feedback for your documentation team.
]]></template>
</review_findings>
</findings_communication>
@ -92,18 +89,14 @@ This feedback can be copied and pasted for your documentation team.
<output_formatting>
<markdown_standards>
<heading_hierarchy>
<rule>Use # for main title only</rule>
<rule>Use ## for major sections</rule>
<rule>Use ### for subsections</rule>
<rule>Use #### sparingly for minor subsections</rule>
<rule>Never skip heading levels</rule>
</heading_hierarchy>
<headings>
<rule>Use # for main title, ## for major sections, ### for subsections.</rule>
<rule>Never skip heading levels.</rule>
</headings>
<code_blocks>
<rule>Always specify language for syntax highlighting</rule>
<rule>Use appropriate language identifiers (typescript, javascript, json, yaml, bash)</rule>
<rule>Include file paths as comments when relevant</rule>
<rule>Always specify language for syntax highlighting (e.g., typescript, json, bash).</rule>
<rule>Include file paths as comments where relevant.</rule>
<example><![CDATA[
```typescript
// src/auth/auth.service.ts
@ -117,9 +110,9 @@ export class AuthService {
</code_blocks>
<tables>
<rule>Use tables for structured data like configurations</rule>
<rule>Include headers with proper alignment</rule>
<rule>Keep cell content concise</rule>
<rule>Use tables for structured data like configs.</rule>
<rule>Include headers and align columns.</rule>
<rule>Keep cell content brief.</rule>
<example><![CDATA[
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
@ -129,30 +122,25 @@ export class AuthService {
</tables>
<lists>
<rule>Use bullet points for unordered lists</rule>
<rule>Use numbers for sequential steps</rule>
<rule>Nest lists with proper indentation</rule>
<rule>Keep list items parallel in structure</rule>
<rule>Use bullets for unordered lists, numbers for sequential steps.</rule>
<rule>Keep list items parallel in structure.</rule>
</lists>
</markdown_standards>
<cross_references>
<internal_links>
<format>[Link text](#section-anchor)</format>
<rule>Use lowercase, hyphenated anchors</rule>
<rule>Test all internal links</rule>
<rule>Use lowercase, hyphenated anchors. Test all links.</rule>
</internal_links>
<external_links>
<format>[Link text](https://example.com)</format>
<rule>Use HTTPS when available</rule>
<rule>Link to official documentation</rule>
<rule>Use HTTPS. Link to official docs.</rule>
</external_links>
<file_references>
<format>`path/to/file.ts`</format>
<rule>Use relative paths from project root</rule>
<rule>Use backticks for inline file references</rule>
<rule>Use relative paths from project root, in backticks.</rule>
</file_references>
</cross_references>
@ -160,15 +148,15 @@ export class AuthService {
<alerts>
<type name="warning">
<format>> ⚠️ **Warning**: [message]</format>
<use_for>Security concerns, breaking changes, deprecations</use_for>
<use_for>Security, breaking changes, deprecations.</use_for>
</type>
<type name="note">
<format>> 📝 **Note**: [message]</format>
<use_for>Important information, clarifications</use_for>
<use_for>Important info, clarifications.</use_for>
</type>
<type name="tip">
<format>> 💡 **Tip**: [message]</format>
<use_for>Best practices, optimization suggestions</use_for>
<use_for>Best practices, optimizations.</use_for>
</type>
</alerts>
@ -186,138 +174,110 @@ Status: Stable
</output_formatting>
<documentation_tone>
<general_principles>
<principle>Be conversational and approachable</principle>
<principle>Use active voice and "you" to address the reader</principle>
<principle>Lead with benefits, not features</principle>
<principle>Use concrete examples and scenarios</principle>
<principle>Keep paragraphs short and scannable</principle>
<principle>Avoid unnecessary technical details</principle>
</general_principles>
<general>
<principle>Be direct, not conversational.</principle>
<principle>Use active voice.</principle>
<principle>Lead with benefits.</principle>
<principle>Use concrete examples.</principle>
<principle>Keep paragraphs short.</principle>
<principle>Avoid unnecessary technical details.</principle>
</general>
<user_focused_tone>
<guideline>Write as if explaining to a colleague who isn't technical</guideline>
<guideline>Use analogies and comparisons to familiar concepts</guideline>
<guideline>Focus on "what" and "why" before "how"</guideline>
<guideline>Include practical examples users can relate to</guideline>
<guideline>Address common concerns and questions directly</guideline>
</user_focused_tone>
<audience_specific_tone>
<audience type="default_user">
<tone>Friendly, helpful, encouraging</tone>
<vocabulary>Plain language, minimal jargon</vocabulary>
<examples>Real-world scenarios, before/after comparisons</examples>
<structure>Problem → Solution → Benefits → How to use</structure>
<audience_tone>
<audience type="developer">
<tone>Technical and direct.</tone>
<vocabulary>Standard programming terms.</vocabulary>
<examples>Code snippets, implementation details.</examples>
</audience>
<audience type="developers">
<tone>Technical when needed, but still approachable</tone>
<vocabulary>Use standard programming terminology</vocabulary>
<examples>Include code snippets and implementation details</examples>
<audience type="end_user">
<tone>Instructional, step-by-step.</tone>
<vocabulary>Simple language, no jargon.</vocabulary>
<examples>Screenshots, real-world scenarios.</examples>
</audience>
<audience type="end_users">
<tone>Friendly, instructional, step-by-step</tone>
<vocabulary>Avoid technical jargon, explain concepts simply</vocabulary>
<examples>Use screenshots and real-world scenarios</examples>
<audience type="administrator">
<tone>Operational focus.</tone>
<vocabulary>IT/DevOps terms.</vocabulary>
<examples>CLI examples, configs.</examples>
</audience>
<audience type="administrators">
<tone>Professional, operational focus</tone>
<vocabulary>Use IT/DevOps terminology</vocabulary>
<examples>Include command-line examples and configurations</examples>
</audience>
<audience type="stakeholders">
<tone>Business-oriented, value-focused</tone>
<vocabulary>Use business terminology, avoid implementation details</vocabulary>
<examples>Include metrics, ROI, and business benefits</examples>
</audience>
</audience_specific_tone>
</audience_tone>
</documentation_tone>
<completion_message>
<structure>
<element>Summary of what was documented</element>
<element>Key findings or insights</element>
<element>File location and name</element>
<element>Suggestions for next steps (if applicable)</element>
<element>Summary of documented feature.</element>
<element>Key findings.</element>
<element>File location.</element>
<element>Next step suggestions (if applicable).</element>
</structure>
<example><![CDATA[
I've completed the comprehensive documentation extraction for the authentication system.
Documentation extracted for the authentication system.
**Documentation Generated**: `DOCS-TEMP-authentication-system.md`
**Generated File**: `DOCS-TEMP-authentication-system.md`
**Key Findings**:
- The system uses JWT tokens with refresh token rotation
- Found 5 main API endpoints for authentication
- Identified 12 configuration options
- Documented security measures including bcrypt hashing and rate limiting
- Included troubleshooting for 3 common issues
- System uses JWT with refresh token rotation.
- 5 API endpoints found.
- 12 configuration options identified.
- Security measures (bcrypt, rate limiting) documented.
- Troubleshooting for 3 common issues included.
**Coverage**:
- ✅ Technical implementation details
- ✅ API reference with examples
- ✅ Technical details
- ✅ API reference
- ✅ Configuration guide
- ✅ Security considerations
- ✅ Security guide
- ✅ User and developer guides
- ✅ Troubleshooting section
The documentation is structured for multiple audiences and includes all requested metadata, version information, and cross-references.
- ✅ Troubleshooting
]]></example>
<example_review><![CDATA[
I have completed the review of the provided documentation section.
Review of the documentation section is complete.
**Action Taken**:
- Analyzed the provided text against the current codebase for accuracy.
- Identified several areas for improvement and outlined them as a recommendation.
**Action**:
- Analyzed text against codebase.
- Identified inaccuracies and omissions.
- Formulated recommendations.
**Next Steps**:
- The detailed feedback has been provided in the chat. You can copy and paste it to your documentation team. No files were created.
- Feedback is in the chat. No files were created.
]]></example_review>
</completion_message>
<error_handling>
<common_scenarios>
<scenarios>
<scenario type="feature_not_found">
<response>
I couldn't find a feature matching "[feature name]". Here are some similar features I found:
Could not find a feature matching "[feature name]". Similar features found:
- [List similar features]
Would you like me to document one of these instead?
Document one of these instead?
</response>
</scenario>
<scenario type="insufficient_code_documentation">
<scenario type="insufficient_docs">
<response>
The code for [feature] has limited inline documentation. I'll extract what I can from:
- Code structure and naming
- Test files
- Related documentation
- Usage patterns
Code for [feature] has limited inline documentation. Extracting from code structure, tests, and usage patterns.
</response>
</scenario>
<scenario type="complex_feature">
<response>
This feature is quite complex with [X] components. Would you like me to:
- Document everything comprehensively (may result in a large document)
- Focus on the core functionality
- Split into multiple documentation files
This feature is complex. Choose documentation scope:
- Document comprehensively
- Focus on core functionality
- Split into multiple documents
</response>
</scenario>
</common_scenarios>
</scenarios>
</error_handling>
<quality_checks>
<before_completion>
<check>All sections have content (no placeholders)</check>
<check>Code examples are syntactically correct</check>
<check>Links and cross-references work</check>
<check>Tables are properly formatted</check>
<check>Version information is included</check>
<check>File naming follows convention</check>
<check>No placeholder content remains.</check>
<check>Code examples are correct.</check>
<check>Links and cross-references work.</check>
<check>Tables are formatted correctly.</check>
<check>Version info is included.</check>
<check>Filename follows conventions.</check>
</before_completion>
</quality_checks>
</communication_guidelines>

252
.roo/rules-docs-extractor/7_user_friendly_examples.xml
View file

@ -1,93 +1,87 @@
<user_friendly_examples>
<overview>
Examples and patterns for creating documentation that prioritizes user experience
and practical understanding over technical completeness.
Examples for creating user-focused, practical documentation.
</overview>
<writing_principles>
<principle name="lead_with_benefits">
<bad>The concurrent file read feature uses parallel processing to read multiple files.</bad>
<good>Read multiple files at once, saving time and reducing interruptions.</good>
<principle name="benefits_over_features">
<bad>The concurrent file read feature uses parallel processing.</bad>
<good>Read multiple files at once, reducing interruptions.</good>
</principle>
<principle name="use_scenarios">
<bad>This feature improves efficiency.</bad>
<good>Instead of approving 10 file reads one by one, approve them all at once and get your answer faster.</good>
<bad>This improves efficiency.</bad>
<good>Instead of approving 10 file reads one-by-one, approve them all at once.</good>
</principle>
<principle name="avoid_implementation_details">
<bad>The feature uses a thread pool with configurable concurrency limits to process file I/O operations.</bad>
<good>Roo can read up to 100 files at once (you can change this limit in settings).</good>
<principle name="hide_implementation_details">
<bad>The feature uses a thread pool with configurable concurrency limits.</bad>
<good>Roo reads up to 100 files at once (changeable in settings).</good>
</principle>
<principle name="conversational_tone">
<principle name="direct_tone">
<bad>Users must configure the concurrent file read limit parameter.</bad>
<good>You can adjust how many files Roo reads at once in the settings.</good>
<good>Adjust how many files Roo reads at once in settings.</good>
</principle>
</writing_principles>
<structure_examples>
<example name="feature_introduction">
<example name="feature_intro">
<template><![CDATA[
# [Feature Name]
[One-sentence description of what it does for the user]
[One-sentence description of what it does.]
### Key Features
- [Benefit 1 - what users can do]
- [Benefit 2 - what problem it solves]
- [Benefit 3 - how it makes life easier]
- [Benefit 1]
- [Benefit 2]
- [Benefit 3]
---
]]></template>
</example>
<example name="why_it_matters">
<example name="use_case">
<template><![CDATA[
## Why This Matters
## Use Case
**Without [feature]**: [Description of the painful old way]
- [Specific pain point]
- [Another pain point]
- [Time/effort wasted]
**Before**: [Description of the old way]
- [Pain point]
- [Pain point]
**With [feature]**: [Description of the better experience]
**Now**: [Description of the new way]
]]></template>
</example>
<example name="configuration_section">
<example name="configuration">
<template><![CDATA[
## Configuration
You can customize this feature in Roo's settings:
Customize this feature in settings:
1. **[Human-friendly setting name]**
- What it does: [Plain language explanation]
- Default: [Default value] (this works well for most users)
- When to change: [Specific scenarios when users might want to adjust this]
1. **[Setting Name]**
- **Does**: [Plain language explanation.]
- **Default**: [Default value.] (Works for most.)
- **Change if**: [Specific scenarios to adjust this.]
2. **[Another setting]**
- What it does: [Plain language explanation]
- Default: [Default value]
- Try changing this if: [Specific use case]
2. **[Setting Name]**
- **Does**: [Plain language explanation.]
- **Default**: [Default value.]
- **Change if**: [Specific use case.]
]]></template>
</example>
<example name="common_questions">
<example name="faq">
<template><![CDATA[
## Common Questions
## FAQ
**"[Actual question users ask]"**
[Direct, helpful answer]
[Optional: Additional tip or context]
**"[User question]"**
- [Direct answer.]
- [Optional tip.]
**"[Another real question]"**
[Answer that addresses the concern]
[Optional: Link to more info]
**"[Technical question simplified]"**
[Non-technical explanation]
[Optional: "For developers:" with technical details]
**"[Another question]"**
- [Direct answer.]
- [Optional link.]
]]></template>
</example>
@ -95,160 +89,130 @@ You can customize this feature in Roo's settings:
<template><![CDATA[
## Troubleshooting
### [Problem symptom users would recognize]
**What's happening**: [Brief explanation]
**Quick fix**: [Immediate solution]
**If that doesn't work**: [Alternative solution]
### [Problem symptom]
**Cause**: [Brief explanation.]
**Fix**: [Immediate solution.]
**Alternate fix**: [Alternative solution.]
### [Another common issue]
**You might see this when**: [Scenario]
**Solution**:
1. [First step]
2. [Second step]
3. [If needed, third step]
### [Another issue]
**Scenario**: [When this happens.]
**Solution**:
1. [Step 1]
2. [Step 2]
]]></template>
</example>
<example name="help_section">
<template><![CDATA[
## Need Help?
Still having issues? Here's how to get help:
1. **Check our FAQ**: [Link to FAQ] - answers to common questions
2. **Report a bug**: [GitHub Issues link] - we typically respond within 24 hours
3. **Join the community**: [Discord/Forum link] - get help from other users
When reporting an issue, please include:
- What you were trying to do
- What happened instead
- Any error messages you saw
]]></template>
</example>
</structure_examples>
<tone_examples>
<friendly_explanations>
<example context="explaining a limit">
<explanations>
<example context="limit">
<technical>The system imposes a hard limit of 100 concurrent operations.</technical>
<friendly>Roo can handle up to 100 files at once - more than enough for most projects!</friendly>
<direct>Roo handles up to 100 files at once.</direct>
</example>
<example context="describing an error">
<example context="error">
<technical>Error: Maximum concurrency threshold exceeded.</technical>
<friendly>Oops! That's too many files at once. Try lowering the file limit in settings.</friendly>
<direct>Too many files requested. Lower the file limit in settings.</direct>
</example>
<example context="explaining a benefit">
<example context="benefit">
<technical>Reduces API call overhead through request batching.</technical>
<friendly>Get answers faster by reading all the files Roo needs in one go.</friendly>
<direct>Get answers faster by reading all needed files at once.</direct>
</example>
</friendly_explanations>
</explanations>
<visual_elements>
<use_emojis_sparingly>
<when>Error messages: ⚠️</when>
<when>Tips: 💡</when>
<when>Important notes: 📝</when>
<visuals>
<emojis>
<when>Error: ⚠️</when>
<when>Tip: 💡</when>
<when>Note: 📝</when>
<when>Security: 🔒</when>
</use_emojis_sparingly>
</emojis>
<use_formatting>
<bold>For emphasis on key points</bold>
<code>For settings names, file paths, or commands</code>
<blockquotes>For important callouts or warnings</blockquotes>
</use_formatting>
</visual_elements>
<formatting>
<bold>For emphasis</bold>
<code>For settings, file paths, or commands</code>
<blockquotes>For callouts or warnings</blockquotes>
</formatting>
</visuals>
</tone_examples>
<real_world_example>
<title>Concurrent File Reads Documentation</title>
<title>Concurrent File Reads Doc</title>
<content><![CDATA[
# Concurrent File Reads
The Concurrent File Reads feature allows Roo to read multiple files from your workspace in a single step. This significantly improves efficiency when working on tasks that require context from several files.
Read multiple files from your workspace in a single step.
### Key Features
- Read up to 100 files in a single request
- Enabled by default for a faster, more streamlined workflow
- Configurable to match your preferences and system capabilities
- Read up to 100 files in one request.
- Enabled by default for faster workflow.
- Configurable to match system capabilities.
---
## Why This Matters
## Use Case
**Previously**: When Roo needed to understand your project, you'd see multiple requests like:
- "Can I read `src/app.js`?" → You approve
- "Now can I read `src/utils.js`?" → You approve
- "And can I read `src/config.json`?" → You approve
**Before**: Multiple, sequential requests to read files:
- "Read `src/app.js`?" → Approve
- "Read `src/utils.js`?" → Approve
- "Read `src/config.json`?" → Approve
**With concurrent file reads**: Roo asks once to read all related files together, getting the full picture immediately and providing better assistance faster.
**Now**: Roo asks once to read all related files.
## How it Works
When you ask Roo to perform a task that involves multiple files, it will automatically identify the relevant files and read them together. This is especially useful for:
Roo automatically identifies and reads relevant files together for tasks requiring multi-file context, such as:
- Understanding components split across multiple files
- Refactoring code with dependencies
- Answering questions that require broad project context
- Understanding components split across multiple files.
- Refactoring code with dependencies.
- Answering questions requiring broad project context.
The [`read_file`](/advanced-usage/available-tools/read-file) tool automatically accepts multiple files in a single request.
The [`read_file`](/tools/read-file) tool accepts multiple files in a single request.
---
## Configuration
You can customize this feature in Roo's settings:
Customize in Roo's settings:
1. **Enable/Disable Concurrent File Reads**
- What it does: Controls whether Roo can read multiple files at once
- Default: Enabled (recommended for most users)
- When to disable: If using a less capable AI model or wanting more control
- **Does**: Toggles whether Roo can read multiple files at once.
- **Default**: Enabled.
- **Disable if**: Using a less capable AI model or requiring more access control.
2. **Concurrent File Reads Limit**
- What it does: Sets the maximum number of files Roo can read at once
- Default: 100 files
- When to adjust: Lower if you have memory constraints, raise for very large projects
- **Does**: Sets max number of files Roo can read at once.
- **Default**: 100.
- **Adjust**: Lower for memory constraints; raise for very large projects.
---
## Benefits
## FAQ
- **Faster Results**: Get comprehensive answers without multiple approval steps
- **Better Context**: Roo understands file relationships immediately
- **Less Interruption**: Approve once and continue working while Roo analyzes
**"Too many files are requested at once."**
- Lower the file limit in settings.
- Deny individual files in the batch dialog.
## Common Questions
**"Some files were denied but others were approved."**
- Normal behavior. Roo works with approved files.
- Files may be blocked by `.rooignore` settings.
**"Roo is asking for too many files at once"**
- Lower the concurrent file limit in settings
- You can still approve or deny individual files in the batch dialog
**"Does this use more memory?"**
- Yes, but the impact is usually minimal.
- If you see slowdowns, reduce the file limit.
**"Some files were denied but others approved"**
- This is normal - Roo works with the files you approve
- Files might be blocked by your `.rooignore` settings
**"Will this use more memory?"**
- Yes, but the impact is usually minimal
- If you notice slowdowns, try reducing the file limit
## Need Help?
If you run into issues:
1. Check the [FAQ section](/faq) for common solutions
2. Report problems on [GitHub Issues](https://github.com/RooCodeInc/Roo-Code/issues)
3. Include what you were trying to do and any error messages
]]></content>
</real_world_example>
<checklist>
<item>Does it start with benefits, not features?</item>
<item>Are technical terms explained or avoided?</item>
<item>Does it use "you" to address the reader?</item>
<item>Are there practical examples or scenarios?</item>
<item>Is the tone conversational and friendly?</item>
<item>Does it start with benefits?</item>
<item>Are technical terms avoided?</item>
<item>Is the tone direct?</item>
<item>Are there practical examples?</item>
<item>Are sections short and scannable?</item>
<item>Does it answer common user questions?</item>
<item>Is help easily accessible?</item>
<item>Does it answer user questions?</item>
<item>Is help accessible?</item>
</checklist>
</user_friendly_examples>