mirror of
https://github.com/RooVetGit/Roo-Code.git
synced 2026-08-28 05:27:24 +00:00
Docs extractor mode (#4621)
This commit is contained in:
Hannes Rudolph
GitHub
parent
a1b8b12928
commit
fc82485563
8 changed files with 3000 additions and 0 deletions
238
.roo/rules-docs-extractor/1_extraction_workflow.xml
Normal file
238
.roo/rules-docs-extractor/1_extraction_workflow.xml
Normal file
|
|
@ -0,0 +1,238 @@
|
|||
<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.
|
||||
</mode_overview>
|
||||
|
||||
<initialization_phase>
|
||||
<step number="1">
|
||||
<title>Understand Documentation 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>
|
||||
</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>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<title>Initial Feature Discovery</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>
|
||||
</actions>
|
||||
<tool_use><![CDATA[
|
||||
<codebase_search>
|
||||
<query>[feature name] implementation main entry point</query>
|
||||
</codebase_search>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
</initialization_phase>
|
||||
|
||||
<analysis_phases>
|
||||
<phase name="code_analysis">
|
||||
<title>Technical Implementation Analysis</title>
|
||||
<steps>
|
||||
<step>
|
||||
<action>Analyze source 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
|
||||
</details>
|
||||
</step>
|
||||
<step>
|
||||
<action>Extract API specifications</action>
|
||||
<details>
|
||||
- REST endpoints with methods and parameters
|
||||
- GraphQL schemas and resolvers
|
||||
- WebSocket events and handlers
|
||||
- RPC interfaces and protocols
|
||||
</details>
|
||||
</step>
|
||||
<step>
|
||||
<action>Document configuration options</action>
|
||||
<details>
|
||||
- Environment variables
|
||||
- Configuration files and schemas
|
||||
- Feature flags and toggles
|
||||
- Runtime parameters
|
||||
</details>
|
||||
</step>
|
||||
</steps>
|
||||
</phase>
|
||||
|
||||
<phase name="business_logic_analysis">
|
||||
<title>Business Logic and Workflow Extraction</title>
|
||||
<steps>
|
||||
<step>
|
||||
<action>Map user workflows</action>
|
||||
<details>
|
||||
- User journey through the feature
|
||||
- Decision points and branching logic
|
||||
- State transitions and lifecycle
|
||||
- User roles and permissions
|
||||
</details>
|
||||
</step>
|
||||
<step>
|
||||
<action>Document business rules</action>
|
||||
<details>
|
||||
- Validation logic and constraints
|
||||
- Calculation formulas and algorithms
|
||||
- Business process implementations
|
||||
- Compliance and regulatory 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
|
||||
</details>
|
||||
</step>
|
||||
</steps>
|
||||
</phase>
|
||||
|
||||
<phase name="integration_analysis">
|
||||
<title>Dependencies and Integration Analysis</title>
|
||||
<steps>
|
||||
<step>
|
||||
<action>Map external dependencies</action>
|
||||
<details>
|
||||
- Third-party libraries and versions
|
||||
- External services and APIs
|
||||
- Database connections and schemas
|
||||
- Message queues and event systems
|
||||
</details>
|
||||
</step>
|
||||
<step>
|
||||
<action>Document integration points</action>
|
||||
<details>
|
||||
- Incoming webhooks and callbacks
|
||||
- Outgoing API calls
|
||||
- Event publishers and subscribers
|
||||
- Shared data stores and caches
|
||||
</details>
|
||||
</step>
|
||||
<step>
|
||||
<action>Analyze data flow</action>
|
||||
<details>
|
||||
- Input data sources and formats
|
||||
- Data transformations and mappings
|
||||
- Output formats and destinations
|
||||
- Data retention and lifecycle
|
||||
</details>
|
||||
</step>
|
||||
</steps>
|
||||
</phase>
|
||||
|
||||
<phase name="quality_analysis">
|
||||
<title>Quality and Testing Analysis</title>
|
||||
<steps>
|
||||
<step>
|
||||
<action>Assess test coverage</action>
|
||||
<details>
|
||||
- Unit test coverage and quality
|
||||
- Integration test scenarios
|
||||
- End-to-end test flows
|
||||
- Performance test results
|
||||
</details>
|
||||
</step>
|
||||
<step>
|
||||
<action>Document error handling</action>
|
||||
<details>
|
||||
- Error types and codes
|
||||
- Exception handling strategies
|
||||
- Fallback mechanisms
|
||||
- Recovery procedures
|
||||
</details>
|
||||
</step>
|
||||
<step>
|
||||
<action>Identify quality metrics</action>
|
||||
<details>
|
||||
- Code complexity metrics
|
||||
- Performance benchmarks
|
||||
- Security vulnerability assessments
|
||||
- Maintainability indices
|
||||
</details>
|
||||
</step>
|
||||
</steps>
|
||||
</phase>
|
||||
|
||||
<phase name="security_analysis">
|
||||
<title>Security and Compliance Analysis</title>
|
||||
<steps>
|
||||
<step>
|
||||
<action>Document security measures</action>
|
||||
<details>
|
||||
- Authentication mechanisms
|
||||
- Authorization and access control
|
||||
- Data encryption methods
|
||||
- Security headers and policies
|
||||
</details>
|
||||
</step>
|
||||
<step>
|
||||
<action>Identify vulnerabilities</action>
|
||||
<details>
|
||||
- Known security issues
|
||||
- Potential attack vectors
|
||||
- Mitigation strategies
|
||||
- Security best practices
|
||||
</details>
|
||||
</step>
|
||||
<step>
|
||||
<action>Compliance requirements</action>
|
||||
<details>
|
||||
- Regulatory compliance (GDPR, HIPAA, etc.)
|
||||
- Industry standards adherence
|
||||
- Audit trail requirements
|
||||
- Data privacy considerations
|
||||
</details>
|
||||
</step>
|
||||
</steps>
|
||||
</phase>
|
||||
</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>
|
||||
<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>
|
||||
<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>
|
||||
</actions>
|
||||
</step>
|
||||
<step number="2">
|
||||
<title>Path 2: Generate New Documentation</title>
|
||||
<note>This path is followed if the user requested new documentation.</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>
|
||||
</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>
|
||||
</completion_criteria>
|
||||
</extraction_workflow>
|
||||
419
.roo/rules-docs-extractor/2_documentation_patterns.xml
Normal file
419
.roo/rules-docs-extractor/2_documentation_patterns.xml
Normal file
|
|
@ -0,0 +1,419 @@
|
|||
<documentation_patterns>
|
||||
<overview>
|
||||
Standard patterns and templates for structuring extracted documentation
|
||||
to serve end-users with clear, practical information.
|
||||
</overview>
|
||||
|
||||
<output_structure>
|
||||
<user_focused_template><![CDATA[
|
||||
# [Feature Name]
|
||||
|
||||
[Brief, clear description of what the feature does and why it matters to users]
|
||||
|
||||
### Key Features
|
||||
- [Feature 1 - written in user-friendly terms]
|
||||
- [Feature 2 - focus on benefits]
|
||||
- [Feature 3 - avoid technical jargon]
|
||||
|
||||
---
|
||||
|
||||
## Why This Matters
|
||||
|
||||
[Explain the problem this solves with a real-world example, like:]
|
||||
|
||||
**[Before scenario]**: [Description of the old/manual way]
|
||||
- [Pain point 1]
|
||||
- [Pain point 2]
|
||||
|
||||
**[With this feature]**: [Description of the improved experience]
|
||||
|
||||
## How it Works
|
||||
|
||||
[Simple explanation of the feature's operation, avoiding implementation details]
|
||||
|
||||
[Include visual representation if helpful - suggest where diagrams would help]
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
[User-friendly explanation of settings]
|
||||
|
||||
1. **[Setting Name]**:
|
||||
- **Setting**: `[Technical name if needed]`
|
||||
- **Description**: [What this does in plain language]
|
||||
- **Default**: [Default value and what it means]
|
||||
|
||||
2. **[Setting Name]**:
|
||||
- **Setting**: `[Technical name if needed]`
|
||||
- **Description**: [What this does in plain language]
|
||||
- **Default**: [Default value and what it means]
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
- **[Benefit 1]**: [Explanation of how this helps]
|
||||
- **[Benefit 2]**: [Explanation of how this helps]
|
||||
- **[Benefit 3]**: [Explanation of how this helps]
|
||||
|
||||
## Common Questions
|
||||
|
||||
**"[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
|
||||
|
||||
## 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)
|
||||
|
||||
[Rest of comprehensive template remains available for technical documentation needs]
|
||||
]]></comprehensive_template>
|
||||
</output_structure>
|
||||
|
||||
<user_friendly_patterns>
|
||||
<before_after_examples>
|
||||
<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
|
||||
|
||||
**Now**: Roo asks once to read all related files together, getting the full picture immediately.
|
||||
]]></template>
|
||||
</before_after_examples>
|
||||
|
||||
<visual_separators>
|
||||
<use_case>Between major sections</use_case>
|
||||
<format>---</format>
|
||||
<purpose>Improve readability and scanning</purpose>
|
||||
</visual_separators>
|
||||
|
||||
<conversational_questions>
|
||||
<template><![CDATA[
|
||||
## Common Questions
|
||||
|
||||
**"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
|
||||
|
||||
**"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
|
||||
]]></template>
|
||||
</conversational_questions>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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
|
||||
|
||||
**"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
|
||||
]]></template>
|
||||
</troubleshooting_section>
|
||||
|
||||
<help_section>
|
||||
<template>< 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
|
||||
]]></template>
|
||||
</help_section>
|
||||
</user_friendly_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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<audience type="stakeholders">
|
||||
<focus_areas>
|
||||
<area>Business value and ROI</area>
|
||||
<area>Feature capabilities and limitations</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>
|
||||
</audience>
|
||||
</audience_specific_sections>
|
||||
|
||||
<metadata_patterns>
|
||||
<version_info>
|
||||
<template><![CDATA[
|
||||
### Version Compatibility Matrix
|
||||
| Component | Min Version | Recommended | Max Version | 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]
|
||||
]]></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]
|
||||
]]></template>
|
||||
</security_warning>
|
||||
|
||||
<performance_note>
|
||||
<template><![CDATA[
|
||||
> ⚡ **Performance Impact**
|
||||
>
|
||||
> [Description of performance consideration]
|
||||
> - **Impact**: [metrics/benchmarks]
|
||||
> - **Optimization**: [recommended approach]
|
||||
> - **Trade-offs**: [considerations]
|
||||
]]></template>
|
||||
</performance_note>
|
||||
</metadata_patterns>
|
||||
|
||||
<code_documentation_patterns>
|
||||
<api_endpoint>
|
||||
<template><![CDATA[
|
||||
### `[METHOD] /api/[path]`
|
||||
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Authentication**: [Required/Optional] - [Type]
|
||||
|
||||
**Parameters**:
|
||||
| Name | Type | Required | Description | Example |
|
||||
|------|------|----------|-------------|---------|
|
||||
| [param] | [type] | [Yes/No] | [description] | [example] |
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"field": "value"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
- **Success (200)**:
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
- **Error (4xx/5xx)**:
|
||||
```json
|
||||
{
|
||||
"error": "error_code",
|
||||
"message": "Human readable message"
|
||||
}
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
curl -X [METHOD] https://api.example.com/[path] \
|
||||
-H "Authorization: Bearer [token]" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"field": "value"}'
|
||||
```
|
||||
]]></template>
|
||||
</api_endpoint>
|
||||
|
||||
<function_documentation>
|
||||
<template><![CDATA[
|
||||
### `functionName(parameters)`
|
||||
|
||||
**Purpose**: [What this function does]
|
||||
|
||||
**Parameters**:
|
||||
- `param1` (Type): [Description]
|
||||
- `param2` (Type, optional): [Description] - Default: [value]
|
||||
|
||||
**Returns**: `Type` - [Description of return value]
|
||||
|
||||
**Throws**:
|
||||
- `ErrorType`: [When this error occurs]
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
const result = functionName(value1, value2);
|
||||
// Expected output: [description]
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
- [Important consideration 1]
|
||||
- [Important consideration 2]
|
||||
]]></template>
|
||||
</function_documentation>
|
||||
|
||||
<configuration_option>
|
||||
<template><![CDATA[
|
||||
### `CONFIG_NAME`
|
||||
|
||||
**Type**: `string | number | boolean`
|
||||
|
||||
**Default**: `default_value`
|
||||
|
||||
**Environment Variable**: `APP_CONFIG_NAME`
|
||||
|
||||
**Description**: [What this configuration controls]
|
||||
|
||||
**Valid Values**:
|
||||
- `value1`: [Description]
|
||||
- `value2`: [Description]
|
||||
|
||||
**Example**:
|
||||
```yaml
|
||||
config:
|
||||
name: value
|
||||
```
|
||||
|
||||
**Impact**: [What changes when this is modified]
|
||||
]]></template>
|
||||
</configuration_option>
|
||||
</code_documentation_patterns>
|
||||
|
||||
<cross_reference_patterns>
|
||||
<internal_link>
|
||||
<format>[Link Text](#section-anchor)</format>
|
||||
<example>[See Configuration Guide](#configuration)</example>
|
||||
</internal_link>
|
||||
|
||||
<external_link>
|
||||
<format>[Link Text](https://external.url)</format>
|
||||
<example>[Official Documentation](https://docs.example.com)</example>
|
||||
</external_link>
|
||||
|
||||
<related_feature>
|
||||
<template><: [How it relates]
|
||||
> - [Feature B](../feature-b/README.md): [How it relates]
|
||||
]]></template>
|
||||
</related_feature>
|
||||
|
||||
<see_also>
|
||||
<template><
|
||||
> - [Related Topic 2](#anchor2)
|
||||
> - [External Resource](https://example.com)
|
||||
]]></template>
|
||||
</see_also>
|
||||
</cross_reference_patterns>
|
||||
</documentation_patterns>
|
||||
410
.roo/rules-docs-extractor/3_analysis_techniques.xml
Normal file
410
.roo/rules-docs-extractor/3_analysis_techniques.xml
Normal file
|
|
@ -0,0 +1,410 @@
|
|||
<analysis_techniques>
|
||||
<overview>
|
||||
Comprehensive techniques for analyzing code and extracting documentation-worthy
|
||||
information from various aspects of a codebase.
|
||||
</overview>
|
||||
|
||||
<code_analysis_techniques>
|
||||
<technique name="entry_point_analysis">
|
||||
<description>
|
||||
Identify and analyze main 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>
|
||||
</steps>
|
||||
<tools><![CDATA[
|
||||
<!-- Find entry points -->
|
||||
<codebase_search>
|
||||
<query>main function app.listen server.start router controller handler</query>
|
||||
</codebase_search>
|
||||
|
||||
<!-- Analyze specific entry point -->
|
||||
<read_file>
|
||||
<path>src/controllers/feature.controller.ts</path>
|
||||
</read_file>
|
||||
|
||||
<!-- Find all routes -->
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>(app\.(get|post|put|delete)|@(Get|Post|Put|Delete)|router\.(get|post|put|delete))</regex>
|
||||
</search_files>
|
||||
]]></tools>
|
||||
</technique>
|
||||
|
||||
<technique name="api_extraction">
|
||||
<description>
|
||||
Extract API specifications from code implementations
|
||||
</description>
|
||||
<patterns>
|
||||
<pattern type="rest">
|
||||
<search_regex><![CDATA[
|
||||
(app|router)\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]
|
||||
]]></search_regex>
|
||||
<extraction>
|
||||
- HTTP method
|
||||
- Route path
|
||||
- Path parameters
|
||||
- Query parameters
|
||||
- Request body schema
|
||||
- Response schemas
|
||||
- Status codes
|
||||
</extraction>
|
||||
</pattern>
|
||||
<pattern type="graphql">
|
||||
<search_regex><![CDATA[
|
||||
type\s+(Query|Mutation|Subscription)\s*{[^}]+}|@(Query|Mutation|Resolver)
|
||||
]]></search_regex>
|
||||
<extraction>
|
||||
- Schema types
|
||||
- Resolvers
|
||||
- Input types
|
||||
- Return types
|
||||
- Field arguments
|
||||
</extraction>
|
||||
</pattern>
|
||||
</patterns>
|
||||
</technique>
|
||||
|
||||
<technique name="dependency_mapping">
|
||||
<description>
|
||||
Map all dependencies and integration points
|
||||
</description>
|
||||
<analysis_points>
|
||||
<point>Import statements and require calls</point>
|
||||
<point>Package.json dependencies</point>
|
||||
<point>External API calls</point>
|
||||
<point>Database connections</point>
|
||||
<point>Message queue integrations</point>
|
||||
<point>File system operations</point>
|
||||
</analysis_points>
|
||||
<tools><![CDATA[
|
||||
<!-- Find all imports -->
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>^import\s+.*from\s+['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)</regex>
|
||||
</search_files>
|
||||
|
||||
<!-- Analyze package dependencies -->
|
||||
<read_file>
|
||||
<path>package.json</path>
|
||||
</read_file>
|
||||
|
||||
<!-- Find external API calls -->
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>(fetch|axios|http\.request|request\(|\.get\(|\.post\()</regex>
|
||||
</search_files>
|
||||
]]></tools>
|
||||
</technique>
|
||||
|
||||
<technique name="data_model_extraction">
|
||||
<description>
|
||||
Extract data models, schemas, and type definitions
|
||||
</description>
|
||||
<sources>
|
||||
<source type="typescript">
|
||||
<patterns>
|
||||
- interface definitions
|
||||
- type aliases
|
||||
- class declarations
|
||||
- enum definitions
|
||||
</patterns>
|
||||
</source>
|
||||
<source type="database">
|
||||
<patterns>
|
||||
- Schema definitions
|
||||
- Migration files
|
||||
- Model definitions (ORM)
|
||||
- SQL CREATE statements
|
||||
</patterns>
|
||||
</source>
|
||||
<source type="validation">
|
||||
<patterns>
|
||||
- JSON Schema
|
||||
- Joi/Yup schemas
|
||||
- Validation decorators
|
||||
- Custom validators
|
||||
</patterns>
|
||||
</source>
|
||||
</sources>
|
||||
<extraction_example><![CDATA[
|
||||
<!-- Find TypeScript interfaces -->
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>^export\s+(interface|type|class|enum)\s+(\w+)</regex>
|
||||
</search_files>
|
||||
|
||||
<!-- Find database models -->
|
||||
<search_files>
|
||||
<path>src/models</path>
|
||||
<regex>@(Entity|Table|Model)|class\s+\w+\s+extends\s+(Model|BaseEntity)</regex>
|
||||
</search_files>
|
||||
]]></extraction_example>
|
||||
</technique>
|
||||
|
||||
<technique name="business_logic_extraction">
|
||||
<description>
|
||||
Identify and document business rules and logic
|
||||
</description>
|
||||
<indicators>
|
||||
<indicator>Complex conditional statements</indicator>
|
||||
<indicator>Calculation functions</indicator>
|
||||
<indicator>Validation rules</indicator>
|
||||
<indicator>State machines</indicator>
|
||||
<indicator>Business-specific constants</indicator>
|
||||
<indicator>Domain-specific 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>
|
||||
</documentation_focus>
|
||||
</technique>
|
||||
|
||||
<technique name="error_handling_analysis">
|
||||
<description>
|
||||
Document error handling strategies and recovery mechanisms
|
||||
</description>
|
||||
<analysis_areas>
|
||||
<area>Try-catch blocks and error boundaries</area>
|
||||
<area>Custom error classes and types</area>
|
||||
<area>Error codes and messages</area>
|
||||
<area>Logging strategies</area>
|
||||
<area>Fallback mechanisms</area>
|
||||
<area>Retry logic</area>
|
||||
<area>Circuit breakers</area>
|
||||
</analysis_areas>
|
||||
<search_patterns><![CDATA[
|
||||
<!-- Find error handling -->
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>try\s*{|catch\s*\(|throw\s+new|class\s+\w*Error\s+extends</regex>
|
||||
</search_files>
|
||||
|
||||
<!-- Find error constants -->
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>ERROR_|_ERROR|ErrorCode|errorCode</regex>
|
||||
</search_files>
|
||||
]]></search_patterns>
|
||||
</technique>
|
||||
|
||||
<technique name="security_analysis">
|
||||
<description>
|
||||
Identify security measures and potential vulnerabilities
|
||||
</description>
|
||||
<security_checks>
|
||||
<check category="authentication">
|
||||
<patterns>
|
||||
- JWT implementation
|
||||
- Session management
|
||||
- OAuth flows
|
||||
- API key handling
|
||||
</patterns>
|
||||
</check>
|
||||
<check category="authorization">
|
||||
<patterns>
|
||||
- Role-based access control
|
||||
- Permission checks
|
||||
- Resource ownership validation
|
||||
- Access control lists
|
||||
</patterns>
|
||||
</check>
|
||||
<check category="data_protection">
|
||||
<patterns>
|
||||
- Encryption usage
|
||||
- Hashing algorithms
|
||||
- Sensitive data handling
|
||||
- PII protection
|
||||
</patterns>
|
||||
</check>
|
||||
<check category="input_validation">
|
||||
<patterns>
|
||||
- Input sanitization
|
||||
- SQL injection prevention
|
||||
- XSS protection
|
||||
- CSRF tokens
|
||||
</patterns>
|
||||
</check>
|
||||
</security_checks>
|
||||
</technique>
|
||||
|
||||
<technique name="performance_analysis">
|
||||
<description>
|
||||
Identify performance characteristics and optimization opportunities
|
||||
</description>
|
||||
<analysis_points>
|
||||
<point>Database query patterns (N+1 queries)</point>
|
||||
<point>Caching strategies</point>
|
||||
<point>Async/await 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>API response times</metric>
|
||||
<metric>Memory usage patterns</metric>
|
||||
<metric>Concurrent request handling</metric>
|
||||
</metrics_to_document>
|
||||
</technique>
|
||||
|
||||
<technique name="test_coverage_analysis">
|
||||
<description>
|
||||
Analyze test coverage and quality
|
||||
</description>
|
||||
<test_types>
|
||||
<type name="unit_tests">
|
||||
<location>__tests__, *.test.ts, *.spec.ts</location>
|
||||
<analysis>Function-level coverage</analysis>
|
||||
</type>
|
||||
<type name="integration_tests">
|
||||
<location>integration/, e2e/</location>
|
||||
<analysis>Feature workflow coverage</analysis>
|
||||
</type>
|
||||
<type name="api_tests">
|
||||
<location>api-tests/, *.api.test.ts</location>
|
||||
<analysis>Endpoint coverage</analysis>
|
||||
</type>
|
||||
</test_types>
|
||||
<coverage_analysis><![CDATA[
|
||||
<!-- Find test files -->
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>\.(test|spec)\.(ts|js|tsx|jsx)$</regex>
|
||||
<file_pattern>*.test.ts</file_pattern>
|
||||
</search_files>
|
||||
|
||||
<!-- Analyze test descriptions -->
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>(describe|it|test)\s*\(\s*['"`]([^'"`]+)['"`]</regex>
|
||||
</search_files>
|
||||
]]></coverage_analysis>
|
||||
</technique>
|
||||
|
||||
<technique name="configuration_extraction">
|
||||
<description>
|
||||
Extract all 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>
|
||||
</configuration_sources>
|
||||
<documentation_requirements>
|
||||
<requirement>Default values</requirement>
|
||||
<requirement>Valid value ranges</requirement>
|
||||
<requirement>Impact on behavior</requirement>
|
||||
<requirement>Dependencies between configs</requirement>
|
||||
<requirement>Security implications</requirement>
|
||||
</documentation_requirements>
|
||||
</technique>
|
||||
</code_analysis_techniques>
|
||||
|
||||
<workflow_analysis>
|
||||
<technique name="user_journey_mapping">
|
||||
<description>
|
||||
Map complete 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>
|
||||
</steps>
|
||||
<deliverables>
|
||||
<deliverable>User flow diagrams</deliverable>
|
||||
<deliverable>Step-by-step procedures</deliverable>
|
||||
<deliverable>Decision trees</deliverable>
|
||||
<deliverable>State transition diagrams</deliverable>
|
||||
</deliverables>
|
||||
</technique>
|
||||
|
||||
<technique name="integration_flow_analysis">
|
||||
<description>
|
||||
Document how the feature integrates 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>
|
||||
</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>
|
||||
</documentation_focus>
|
||||
</technique>
|
||||
</workflow_analysis>
|
||||
|
||||
<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>
|
||||
</sources>
|
||||
<extraction_pattern><![CDATA[
|
||||
<!-- Find version requirements -->
|
||||
<search_files>
|
||||
<path>.</path>
|
||||
<regex>"engines":|"peerDependencies":|requires?\s+\w+\s+version|compatible\s+with</regex>
|
||||
</search_files>
|
||||
]]></extraction_pattern>
|
||||
</technique>
|
||||
|
||||
<technique name="deprecation_tracking">
|
||||
<indicators>
|
||||
<indicator>@deprecated annotations</indicator>
|
||||
<indicator>TODO: deprecate comments</indicator>
|
||||
<indicator>Legacy code markers</indicator>
|
||||
<indicator>Migration warnings</indicator>
|
||||
</indicators>
|
||||
<documentation_requirements>
|
||||
<requirement>Deprecation date</requirement>
|
||||
<requirement>Removal timeline</requirement>
|
||||
<requirement>Migration path</requirement>
|
||||
<requirement>Alternative solutions</requirement>
|
||||
</documentation_requirements>
|
||||
</technique>
|
||||
</metadata_extraction>
|
||||
|
||||
<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>
|
||||
</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>
|
||||
</metrics>
|
||||
</indicator>
|
||||
</quality_indicators>
|
||||
</analysis_techniques>
|
||||
398
.roo/rules-docs-extractor/4_tool_usage_guide.xml
Normal file
398
.roo/rules-docs-extractor/4_tool_usage_guide.xml
Normal file
|
|
@ -0,0 +1,398 @@
|
|||
<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.
|
||||
</overview>
|
||||
|
||||
<tool_sequence>
|
||||
<priority level="1">
|
||||
<tool>codebase_search</tool>
|
||||
<purpose>Initial discovery of feature-related code</purpose>
|
||||
<usage_patterns>
|
||||
<pattern>
|
||||
<scenario>Finding feature entry points</scenario>
|
||||
<example><![CDATA[
|
||||
<codebase_search>
|
||||
<query>authentication login user session JWT token</query>
|
||||
</codebase_search>
|
||||
]]></example>
|
||||
</pattern>
|
||||
<pattern>
|
||||
<scenario>Locating business logic</scenario>
|
||||
<example><![CDATA[
|
||||
<codebase_search>
|
||||
<query>calculate pricing discount tax invoice billing</query>
|
||||
</codebase_search>
|
||||
]]></example>
|
||||
</pattern>
|
||||
<pattern>
|
||||
<scenario>Finding configuration</scenario>
|
||||
<example><![CDATA[
|
||||
<codebase_search>
|
||||
<query>config settings environment variables .env process.env</query>
|
||||
</codebase_search>
|
||||
]]></example>
|
||||
</pattern>
|
||||
</usage_patterns>
|
||||
</priority>
|
||||
|
||||
<priority level="2">
|
||||
<tool>list_code_definition_names</tool>
|
||||
<purpose>Understanding code structure and organization</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>
|
||||
</best_practices>
|
||||
<example><![CDATA[
|
||||
<list_code_definition_names>
|
||||
<path>src/features/authentication</path>
|
||||
</list_code_definition_names>
|
||||
]]></example>
|
||||
</priority>
|
||||
|
||||
<priority level="3">
|
||||
<tool>read_file</tool>
|
||||
<purpose>Deep analysis of 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>
|
||||
</strategy>
|
||||
<batch_reading><![CDATA[
|
||||
<read_file>
|
||||
<args>
|
||||
<file>
|
||||
<path>src/controllers/auth.controller.ts</path>
|
||||
</file>
|
||||
<file>
|
||||
<path>src/services/auth.service.ts</path>
|
||||
</file>
|
||||
<file>
|
||||
<path>src/models/user.model.ts</path>
|
||||
</file>
|
||||
<file>
|
||||
<path>src/types/auth.types.ts</path>
|
||||
</file>
|
||||
<file>
|
||||
<path>src/__tests__/auth.test.ts</path>
|
||||
</file>
|
||||
</args>
|
||||
</read_file>
|
||||
]]></batch_reading>
|
||||
</priority>
|
||||
|
||||
<priority level="4">
|
||||
<tool>search_files</tool>
|
||||
<purpose>Finding specific patterns and implementations</purpose>
|
||||
<use_cases>
|
||||
<use_case>
|
||||
<description>Find all API endpoints</description>
|
||||
<example><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>@(Get|Post|Put|Delete|Patch)\(['"]([^'"]+)['"]|router\.(get|post|put|delete|patch)\(['"]([^'"]+)['"]</regex>
|
||||
</search_files>
|
||||
]]></example>
|
||||
</use_case>
|
||||
<use_case>
|
||||
<description>Find error handling patterns</description>
|
||||
<example><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>throw new \w+Error|catch \(|\.catch\(|try \{</regex>
|
||||
</search_files>
|
||||
]]></example>
|
||||
</use_case>
|
||||
<use_case>
|
||||
<description>Find configuration usage</description>
|
||||
<example><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>process\.env\.\w+|config\.get\(['"]([^'"]+)['"]|getConfig\(\)</regex>
|
||||
</search_files>
|
||||
]]></example>
|
||||
</use_case>
|
||||
</use_cases>
|
||||
</priority>
|
||||
</tool_sequence>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
</best_practices>
|
||||
<example><
|
||||
2. [Architecture](#architecture)
|
||||
...
|
||||
|
||||
## Overview
|
||||
The authentication system provides secure user authentication using JWT tokens...
|
||||
</content>
|
||||
<line_count>...</line_count>
|
||||
</write_to_file>
|
||||
]]></example>
|
||||
</tool>
|
||||
|
||||
<tool name="ask_followup_question">
|
||||
<purpose>Clarify requirements when multiple interpretations exist</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>
|
||||
</when_to_use>
|
||||
<examples>
|
||||
<example><![CDATA[
|
||||
<ask_followup_question>
|
||||
<question>Which aspects of the authentication system should I focus on?</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>
|
||||
</follow_up>
|
||||
</ask_followup_question>
|
||||
]]></example>
|
||||
<example><![CDATA[
|
||||
<ask_followup_question>
|
||||
<question>What level of technical detail should the documentation include?</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>
|
||||
</follow_up>
|
||||
</ask_followup_question>
|
||||
]]></example>
|
||||
</examples>
|
||||
</tool>
|
||||
</documentation_generation_tools>
|
||||
|
||||
<analysis_strategies>
|
||||
<strategy name="comprehensive_file_discovery">
|
||||
<description>
|
||||
Systematic approach to finding all files related to a feature
|
||||
</description>
|
||||
<steps>
|
||||
<step>
|
||||
<action>Start with semantic search</action>
|
||||
<tool_use><![CDATA[
|
||||
<codebase_search>
|
||||
<query>feature implementation main logic core functionality</query>
|
||||
</codebase_search>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
<step>
|
||||
<action>List directory structure</action>
|
||||
<tool_use><![CDATA[
|
||||
<list_files>
|
||||
<path>src/features</path>
|
||||
<recursive>true</recursive>
|
||||
</list_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
<step>
|
||||
<action>Find related tests</action>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>describe\(['"].*Feature.*['"]|test\(['"].*feature.*['"]</regex>
|
||||
<file_pattern>*.test.ts</file_pattern>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
<step>
|
||||
<action>Locate configuration files</action>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>.</path>
|
||||
<regex>feature.*config|settings.*feature</regex>
|
||||
<file_pattern>*.json</file_pattern>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
</steps>
|
||||
</strategy>
|
||||
|
||||
<strategy name="dependency_chain_analysis">
|
||||
<description>
|
||||
Follow import chains to understand all 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>
|
||||
</process>
|
||||
<import_patterns><![CDATA[
|
||||
<!-- TypeScript/JavaScript imports -->
|
||||
<search_files>
|
||||
<path>src/feature</path>
|
||||
<regex>import\s+(?:{[^}]+}|\*\s+as\s+\w+|\w+)\s+from\s+['"]([^'"]+)['"]</regex>
|
||||
</search_files>
|
||||
|
||||
<!-- CommonJS requires -->
|
||||
<search_files>
|
||||
<path>src/feature</path>
|
||||
<regex>require\(['"]([^'"]+)['"]\)</regex>
|
||||
</search_files>
|
||||
]]></import_patterns>
|
||||
</strategy>
|
||||
|
||||
<strategy name="api_documentation_extraction">
|
||||
<description>
|
||||
Extract complete 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>
|
||||
</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>
|
||||
</sequence>
|
||||
</tools_sequence>
|
||||
</strategy>
|
||||
|
||||
<strategy name="test_driven_documentation">
|
||||
<description>
|
||||
Use tests to understand 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>
|
||||
</benefits>
|
||||
<extraction_approach><![CDATA[
|
||||
<!-- Find test descriptions -->
|
||||
<search_files>
|
||||
<path>__tests__</path>
|
||||
<regex>(describe|it|test)\(['"]([^'"]+)['"]</regex>
|
||||
</search_files>
|
||||
|
||||
<!-- Extract test scenarios -->
|
||||
<read_file>
|
||||
<path>__tests__/feature.test.ts</path>
|
||||
</read_file>
|
||||
]]></extraction_approach>
|
||||
</strategy>
|
||||
</analysis_strategies>
|
||||
|
||||
<common_patterns>
|
||||
<pattern name="configuration_documentation">
|
||||
<search_locations>
|
||||
<location>.env.example</location>
|
||||
<location>config/*.json</location>
|
||||
<location>src/config/*</location>
|
||||
<location>README.md (configuration section)</location>
|
||||
</search_locations>
|
||||
<extraction_regex><![CDATA[
|
||||
# Environment variables
|
||||
process\.env\.(\w+)
|
||||
|
||||
# Config object access
|
||||
config\.(\w+)\.(\w+)
|
||||
|
||||
# Default values
|
||||
\w+\s*=\s*process\.env\.\w+\s*\|\|\s*['"]([^'"]+)['"]
|
||||
]]></extraction_regex>
|
||||
</pattern>
|
||||
|
||||
<pattern name="error_documentation">
|
||||
<error_patterns>
|
||||
<pattern>Custom error classes</pattern>
|
||||
<pattern>Error code constants</pattern>
|
||||
<pattern>Error message templates</pattern>
|
||||
<pattern>HTTP status codes</pattern>
|
||||
</error_patterns>
|
||||
<search_approach><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>class\s+\w*Error\s+extends|new Error\(|throw new|ERROR_CODE|HTTP_STATUS</regex>
|
||||
</search_files>
|
||||
]]></search_approach>
|
||||
</pattern>
|
||||
|
||||
<pattern name="security_documentation">
|
||||
<security_aspects>
|
||||
<aspect>Authentication methods</aspect>
|
||||
<aspect>Authorization rules</aspect>
|
||||
<aspect>Data encryption</aspect>
|
||||
<aspect>Input validation</aspect>
|
||||
<aspect>Rate limiting</aspect>
|
||||
</security_aspects>
|
||||
<indicators><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>@Authorized|requireAuth|checkPermission|encrypt|decrypt|sanitize|validate|rateLimit</regex>
|
||||
</search_files>
|
||||
]]></indicators>
|
||||
</pattern>
|
||||
</common_patterns>
|
||||
|
||||
<output_optimization>
|
||||
<guideline name="structured_sections">
|
||||
<description>Organize output for easy navigation</description>
|
||||
<structure>
|
||||
- Clear hierarchy with numbered sections
|
||||
- Consistent heading levels
|
||||
- Table of contents with links
|
||||
- Cross-references between sections
|
||||
</structure>
|
||||
</guideline>
|
||||
|
||||
<guideline name="code_examples">
|
||||
<description>Include relevant code examples</description>
|
||||
<best_practices>
|
||||
- Use syntax highlighting
|
||||
- Show both request and response
|
||||
- Include error cases
|
||||
- Provide language-specific examples
|
||||
</best_practices>
|
||||
</guideline>
|
||||
|
||||
<guideline name="visual_aids">
|
||||
<description>Suggest where diagrams would help</description>
|
||||
<diagram_types>
|
||||
- Architecture diagrams
|
||||
- Sequence diagrams
|
||||
- Data flow diagrams
|
||||
- State machines
|
||||
</diagram_types>
|
||||
</guideline>
|
||||
|
||||
<guideline name="metadata_inclusion">
|
||||
<description>Always include important metadata</description>
|
||||
<required_metadata>
|
||||
- Version compatibility
|
||||
- Last updated date
|
||||
- Feature status (stable/beta/deprecated)
|
||||
- Performance characteristics
|
||||
- Security considerations
|
||||
</required_metadata>
|
||||
</guideline>
|
||||
</output_optimization>
|
||||
</tool_usage_guide>
|
||||
943
.roo/rules-docs-extractor/5_complete_extraction_examples.xml
Normal file
943
.roo/rules-docs-extractor/5_complete_extraction_examples.xml
Normal file
|
|
@ -0,0 +1,943 @@
|
|||
<complete_extraction_examples>
|
||||
<overview>
|
||||
Complete examples demonstrating the full documentation extraction workflow
|
||||
for different types of features and components.
|
||||
</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.
|
||||
</scenario>
|
||||
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>Initial feature discovery</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
|
||||
</expected_findings>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<description>Analyze authentication 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
|
||||
</analysis>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<description>Read core implementation files</description>
|
||||
<tool_use><![CDATA[
|
||||
<read_file>
|
||||
<args>
|
||||
<file>
|
||||
<path>src/auth/auth.controller.ts</path>
|
||||
</file>
|
||||
<file>
|
||||
<path>src/auth/auth.service.ts</path>
|
||||
</file>
|
||||
<file>
|
||||
<path>src/auth/jwt.strategy.ts</path>
|
||||
</file>
|
||||
<file>
|
||||
<path>src/auth/auth.guard.ts</path>
|
||||
</file>
|
||||
<file>
|
||||
<path>src/models/user.model.ts</path>
|
||||
</file>
|
||||
</args>
|
||||
</read_file>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<description>Extract API endpoints</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src/auth</path>
|
||||
<regex>@(Post|Get)\(['"]\/auth\/[^'"]+['"]|router\.(post|get)\(['"]\/auth\/[^'"]+['"]</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
<findings>
|
||||
- POST /auth/login
|
||||
- POST /auth/logout
|
||||
- POST /auth/refresh
|
||||
- GET /auth/profile
|
||||
- POST /auth/register
|
||||
</findings>
|
||||
</step>
|
||||
|
||||
<step number="5">
|
||||
<description>Document configuration</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>JWT_SECRET|JWT_EXPIRATION|AUTH_.*|process\.env\.\w*AUTH\w*</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="6">
|
||||
<description>Analyze security measures</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src/auth</path>
|
||||
<regex>bcrypt|hash|salt|encrypt|sanitize|validate|@IsEmail|@MinLength</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="7">
|
||||
<description>Generate documentation</description>
|
||||
<tool_use><
|
||||
2. [Quick Start](#quick-start)
|
||||
3. [Architecture](#architecture)
|
||||
4. [API Reference](#api-reference)
|
||||
5. [Configuration](#configuration)
|
||||
6. [Security](#security)
|
||||
7. [User Guide](#user-guide)
|
||||
8. [Developer Guide](#developer-guide)
|
||||
9. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
### Purpose
|
||||
The authentication system provides secure user authentication using JWT (JSON Web Tokens) with support for:
|
||||
- User registration and login
|
||||
- Token-based authentication
|
||||
- Refresh token rotation
|
||||
- Role-based access control (RBAC)
|
||||
- Session management
|
||||
- Password reset functionality
|
||||
|
||||
### Key Features
|
||||
- **JWT Authentication**: Stateless authentication using signed tokens
|
||||
- **Refresh Tokens**: Long-lived tokens for seamless user experience
|
||||
- **Role-Based Access**: Fine-grained permission control
|
||||
- **Security**: bcrypt password hashing, rate limiting, CSRF protection
|
||||
- **Multi-device Support**: Token management across devices
|
||||
|
||||
### Version Information
|
||||
- **Current Version**: 2.1.0
|
||||
- **Minimum Node.js**: 14.0.0
|
||||
- **Dependencies**:
|
||||
- jsonwebtoken: ^9.0.0
|
||||
- bcrypt: ^5.1.0
|
||||
- passport: ^0.6.0
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### For Users
|
||||
1. Register a new account:
|
||||
```bash
|
||||
POST /api/auth/register
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePassword123!",
|
||||
"name": "John Doe"
|
||||
}
|
||||
```
|
||||
|
||||
2. Login to receive tokens:
|
||||
```bash
|
||||
POST /api/auth/login
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePassword123!"
|
||||
}
|
||||
```
|
||||
|
||||
3. Use the access token in subsequent requests:
|
||||
```bash
|
||||
Authorization: Bearer <access_token>
|
||||
```
|
||||
|
||||
### For Developers
|
||||
```typescript
|
||||
// Import authentication module
|
||||
import { AuthModule } from './auth/auth.module';
|
||||
|
||||
// Configure in app module
|
||||
@Module({
|
||||
imports: [
|
||||
AuthModule.forRoot({
|
||||
jwtSecret: process.env.JWT_SECRET,
|
||||
jwtExpiration: '15m',
|
||||
refreshExpiration: '7d'
|
||||
})
|
||||
]
|
||||
})
|
||||
export class AppModule {}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### System Overview
|
||||
```
|
||||
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||||
│ Client │────▶│ Auth Guard │────▶│ Service │
|
||||
└─────────────┘ └──────────────┘ └─────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌─────────────┐
|
||||
│ JWT Strategy │ │ Database │
|
||||
└──────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
### Components
|
||||
- **AuthController**: Handles HTTP requests for authentication endpoints
|
||||
- **AuthService**: Core authentication logic and token management
|
||||
- **JwtStrategy**: Passport strategy for JWT validation
|
||||
- **AuthGuard**: Route protection middleware
|
||||
- **UserService**: User management and database operations
|
||||
|
||||
### Token Flow
|
||||
1. User provides credentials
|
||||
2. System validates credentials against database
|
||||
3. Generate access token (short-lived) and refresh token (long-lived)
|
||||
4. Client stores tokens securely
|
||||
5. Access token used for API requests
|
||||
6. Refresh token used to obtain new access token
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
### Authentication Endpoints
|
||||
|
||||
#### `POST /api/auth/register`
|
||||
Register a new user account.
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"email": "string (required)",
|
||||
"password": "string (required, min 8 chars)",
|
||||
"name": "string (required)",
|
||||
"role": "string (optional, default: 'user')"
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (201 Created):
|
||||
```json
|
||||
{
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe",
|
||||
"role": "user",
|
||||
"createdAt": "2024-01-01T00:00:00Z"
|
||||
},
|
||||
"tokens": {
|
||||
"accessToken": "jwt_token",
|
||||
"refreshToken": "refresh_token",
|
||||
"expiresIn": 900
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses**:
|
||||
- `400 Bad Request`: Invalid input data
|
||||
- `409 Conflict`: Email already exists
|
||||
|
||||
#### `POST /api/auth/login`
|
||||
Authenticate user and receive tokens.
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"email": "string (required)",
|
||||
"password": "string (required)"
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (200 OK):
|
||||
```json
|
||||
{
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe",
|
||||
"role": "user"
|
||||
},
|
||||
"tokens": {
|
||||
"accessToken": "jwt_token",
|
||||
"refreshToken": "refresh_token",
|
||||
"expiresIn": 900
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses**:
|
||||
- `401 Unauthorized`: Invalid credentials
|
||||
- `429 Too Many Requests`: Rate limit exceeded
|
||||
|
||||
#### `POST /api/auth/refresh`
|
||||
Refresh access token using refresh token.
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string (required)"
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (200 OK):
|
||||
```json
|
||||
{
|
||||
"accessToken": "new_jwt_token",
|
||||
"expiresIn": 900
|
||||
}
|
||||
```
|
||||
|
||||
#### `POST /api/auth/logout`
|
||||
Invalidate refresh token.
|
||||
|
||||
**Headers**:
|
||||
- `Authorization: Bearer <access_token>`
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string (required)"
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (200 OK):
|
||||
```json
|
||||
{
|
||||
"message": "Logged out successfully"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Type | Default | Description |
|
||||
|----------|------|---------|-------------|
|
||||
| `JWT_SECRET` | string | - | Secret key for signing JWT tokens (required) |
|
||||
| `JWT_EXPIRATION` | string | '15m' | Access token expiration time |
|
||||
| `REFRESH_TOKEN_EXPIRATION` | string | '7d' | Refresh token expiration time |
|
||||
| `BCRYPT_ROUNDS` | number | 10 | Number of bcrypt hashing rounds |
|
||||
| `AUTH_RATE_LIMIT` | number | 5 | Max login attempts per minute |
|
||||
| `ENABLE_2FA` | boolean | false | Enable two-factor authentication |
|
||||
|
||||
### Configuration File (auth.config.ts)
|
||||
```typescript
|
||||
export const authConfig = {
|
||||
jwt: {
|
||||
secret: process.env.JWT_SECRET,
|
||||
signOptions: {
|
||||
expiresIn: process.env.JWT_EXPIRATION || '15m',
|
||||
issuer: 'your-app-name',
|
||||
audience: 'your-app-users'
|
||||
}
|
||||
},
|
||||
bcrypt: {
|
||||
rounds: parseInt(process.env.BCRYPT_ROUNDS || '10')
|
||||
},
|
||||
session: {
|
||||
maxDevices: 5,
|
||||
inactivityTimeout: '30d'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
### Authentication Flow
|
||||
1. **Password Storage**: Passwords hashed using bcrypt with configurable rounds
|
||||
2. **Token Security**: JWT tokens signed with RS256 algorithm
|
||||
3. **Refresh Token Rotation**: New refresh token issued on each refresh
|
||||
4. **Rate Limiting**: Prevents brute force attacks on login endpoint
|
||||
|
||||
### Security Best Practices
|
||||
- Store tokens securely (httpOnly cookies recommended)
|
||||
- Implement CSRF protection for cookie-based auth
|
||||
- Use HTTPS in production
|
||||
- Rotate JWT secrets periodically
|
||||
- Implement account lockout after failed attempts
|
||||
- Enable 2FA for sensitive accounts
|
||||
|
||||
### Common Vulnerabilities Addressed
|
||||
- **SQL Injection**: Parameterized queries
|
||||
- **XSS**: Input sanitization and validation
|
||||
- **CSRF**: Token validation
|
||||
- **Brute Force**: Rate limiting and account lockout
|
||||
- **Token Hijacking**: Short expiration times and refresh rotation
|
||||
|
||||
---
|
||||
|
||||
## User Guide
|
||||
|
||||
### Registration Process
|
||||
1. Navigate to registration page
|
||||
2. Enter email, password, and name
|
||||
3. Verify email (if enabled)
|
||||
4. Login with credentials
|
||||
|
||||
### Managing Sessions
|
||||
- View active sessions in account settings
|
||||
- Revoke sessions from other devices
|
||||
- Set session timeout preferences
|
||||
|
||||
### Password Management
|
||||
- Change password from profile settings
|
||||
- Reset forgotten password via email
|
||||
- Password requirements:
|
||||
- Minimum 8 characters
|
||||
- At least one uppercase letter
|
||||
- At least one number
|
||||
- At least one special character
|
||||
|
||||
---
|
||||
|
||||
## Developer Guide
|
||||
|
||||
### Protecting Routes
|
||||
```typescript
|
||||
// Use AuthGuard decorator
|
||||
@UseGuards(AuthGuard('jwt'))
|
||||
@Get('protected')
|
||||
async getProtectedData() {
|
||||
return { data: 'This is protected' };
|
||||
}
|
||||
|
||||
// Role-based protection
|
||||
@UseGuards(AuthGuard('jwt'), RolesGuard)
|
||||
@Roles('admin')
|
||||
@Get('admin')
|
||||
async getAdminData() {
|
||||
return { data: 'Admin only' };
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Authentication Logic
|
||||
```typescript
|
||||
// Extend AuthService
|
||||
export class CustomAuthService extends AuthService {
|
||||
async validateUser(email: string, password: string): Promise<User> {
|
||||
// Add custom validation logic
|
||||
const user = await super.validateUser(email, password);
|
||||
|
||||
// Additional checks
|
||||
if (user.suspended) {
|
||||
throw new UnauthorizedException('Account suspended');
|
||||
}
|
||||
|
||||
return user;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Testing Authentication
|
||||
```typescript
|
||||
describe('AuthController', () => {
|
||||
it('should login user', async () => {
|
||||
const response = await request(app.getHttpServer())
|
||||
.post('/auth/login')
|
||||
.send({
|
||||
email: 'test@example.com',
|
||||
password: 'TestPass123!'
|
||||
})
|
||||
.expect(200);
|
||||
|
||||
expect(response.body).toHaveProperty('tokens.accessToken');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Invalid Token Error
|
||||
**Problem**: "JsonWebTokenError: invalid token"
|
||||
**Solutions**:
|
||||
- Verify token format (Bearer prefix)
|
||||
- Check token expiration
|
||||
- Ensure JWT_SECRET matches
|
||||
|
||||
#### Login Rate Limit
|
||||
**Problem**: "429 Too Many Requests"
|
||||
**Solutions**:
|
||||
- Wait for rate limit window to reset
|
||||
- Check AUTH_RATE_LIMIT configuration
|
||||
- Implement exponential backoff
|
||||
|
||||
#### CORS Issues
|
||||
**Problem**: "Access blocked by CORS policy"
|
||||
**Solutions**:
|
||||
- Configure CORS middleware
|
||||
- Add origin to allowed list
|
||||
- Check preflight requests
|
||||
|
||||
### Debug Mode
|
||||
Enable debug logging:
|
||||
```bash
|
||||
DEBUG=auth:* npm start
|
||||
```
|
||||
|
||||
### Support
|
||||
- GitHub Issues: [github.com/yourapp/issues](https://github.com/yourapp/issues)
|
||||
- Documentation: [docs.yourapp.com/auth](https://docs.yourapp.com/auth)
|
||||
- Email: support@yourapp.com
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
### v2.1.0 (2024-01-15)
|
||||
- Added refresh token rotation
|
||||
- Improved rate limiting
|
||||
- Fixed security vulnerability in password reset
|
||||
|
||||
### v2.0.0 (2023-12-01)
|
||||
- Breaking: Changed token format
|
||||
- Added 2FA support
|
||||
- Improved session management
|
||||
|
||||
### Migration Guide (v1.x to v2.x)
|
||||
1. Update JWT_SECRET format
|
||||
2. Run token migration script
|
||||
3. Update client-side token handling
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
- [JWT.io](https://jwt.io) - JWT Documentation
|
||||
- [OWASP Authentication Guide](https://owasp.org/www-project-cheat-sheets/cheatsheets/Authentication_Cheat_Sheet)
|
||||
- [Passport.js Documentation](http://www.passportjs.org/docs/)
|
||||
</content>
|
||||
<line_count>450</line_count>
|
||||
</write_to_file>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
</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>
|
||||
</key_takeaways>
|
||||
</example>
|
||||
|
||||
<example name="database_schema_extraction">
|
||||
<scenario>
|
||||
Extract documentation for database models, relationships, migrations,
|
||||
and data access patterns.
|
||||
</scenario>
|
||||
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>Find database-related files</description>
|
||||
<tool_use><![CDATA[
|
||||
<codebase_search>
|
||||
<query>database schema model entity migration table column relationship</query>
|
||||
</codebase_search>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<description>Analyze model definitions</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src/models</path>
|
||||
<regex>@(Entity|Table|Model)|class\s+\w+\s+extends\s+(Model|BaseEntity)</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<description>Extract relationships</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src/models</path>
|
||||
<regex>@(OneToMany|ManyToOne|OneToOne|ManyToMany|BelongsTo|HasMany)</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<description>Document migrations</description>
|
||||
<tool_use><![CDATA[
|
||||
<list_files>
|
||||
<path>migrations</path>
|
||||
<recursive>true</recursive>
|
||||
</list_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="5">
|
||||
<description>Generate schema documentation</description>
|
||||
<output>
|
||||
- Entity relationship diagrams
|
||||
- Table schemas with column types
|
||||
- Index definitions
|
||||
- Foreign key constraints
|
||||
- Migration history
|
||||
- Query patterns and optimizations
|
||||
</output>
|
||||
</step>
|
||||
</workflow>
|
||||
</example>
|
||||
|
||||
<example name="api_endpoint_extraction">
|
||||
<scenario>
|
||||
Extract comprehensive API documentation including all endpoints,
|
||||
request/response formats, authentication, and examples.
|
||||
</scenario>
|
||||
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>Find all API routes</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>(app|router)\.(get|post|put|patch|delete|all)\s*\(\s*['"`]([^'"`]+)['"`]</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<description>Extract request validation</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>@(Body|Query|Param|Headers)\(|joi\.object|yup\.object|zod\.object</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<description>Find response schemas</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>@ApiResponse|swagger|openapi|response\.json\(|res\.send\(</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<description>Document authentication requirements</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>@(UseGuards|Authorized|Public)|passport\.authenticate|requireAuth</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="5">
|
||||
<description>Generate OpenAPI/Swagger documentation</description>
|
||||
<output_format>
|
||||
- OpenAPI 3.0 specification
|
||||
- Postman collection
|
||||
- API client examples
|
||||
- cURL commands
|
||||
- SDK usage examples
|
||||
</output_format>
|
||||
</step>
|
||||
</workflow>
|
||||
</example>
|
||||
|
||||
<example name="frontend_component_extraction">
|
||||
<scenario>
|
||||
Document React/Vue/Angular components including props, events,
|
||||
slots, styling, and usage examples.
|
||||
</scenario>
|
||||
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>Find component files</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src/components</path>
|
||||
<regex>export\s+(default\s+)?(function|class|const)\s+\w+|@Component</regex>
|
||||
<file_pattern>*.tsx</file_pattern>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<description>Extract component props/inputs</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src/components</path>
|
||||
<regex>interface\s+\w+Props|type\s+\w+Props|@Input\(\)|props:\s*{</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<description>Find component usage examples</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex><ComponentName|import.*ComponentName</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<description>Document styling and themes</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src/components</path>
|
||||
<regex>styled\.|makeStyles|@apply|className=|style=</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="5">
|
||||
<description>Extract Storybook stories</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>export\s+default\s+{.*title:|\.stories\.</regex>
|
||||
<file_pattern>*.stories.tsx</file_pattern>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="6">
|
||||
<description>Generate component documentation</description>
|
||||
<output>
|
||||
- Component API reference
|
||||
- Props table with types and defaults
|
||||
- Event documentation
|
||||
- Styling guidelines
|
||||
- Usage examples
|
||||
- Accessibility notes
|
||||
- Browser compatibility
|
||||
</output>
|
||||
</step>
|
||||
</workflow>
|
||||
</example>
|
||||
|
||||
<example name="configuration_system_extraction">
|
||||
<scenario>
|
||||
Document all configuration options, environment variables,
|
||||
feature flags, and their impacts on system behavior.
|
||||
</scenario>
|
||||
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>Find configuration files</description>
|
||||
<tool_use><![CDATA[
|
||||
<list_files>
|
||||
<path>.</path>
|
||||
<recursive>false</recursive>
|
||||
</list_files>
|
||||
]]></tool_use>
|
||||
<look_for>
|
||||
- .env.example
|
||||
- config/
|
||||
- settings.json
|
||||
- app.config.ts
|
||||
</look_for>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<description>Extract environment variables</description>
|
||||
<tool_use><['"]\)</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<description>Find feature flags</description>
|
||||
<tool_use><![CDATA[
|
||||
<search_files>
|
||||
<path>src</path>
|
||||
<regex>feature\.|featureFlag|isEnabled\(['"]|flags\.</regex>
|
||||
</search_files>
|
||||
]]></tool_use>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<description>Document configuration impacts</description>
|
||||
<analysis>
|
||||
- How each config affects behavior
|
||||
- Dependencies between configs
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
- Default values and overrides
|
||||
</analysis>
|
||||
</step>
|
||||
|
||||
<step number="5">
|
||||
<description>Generate configuration guide</description>
|
||||
<output>
|
||||
- Complete configuration reference
|
||||
- Environment setup guide
|
||||
- Docker/Kubernetes configs
|
||||
- CI/CD pipeline variables
|
||||
- Production deployment checklist
|
||||
</output>
|
||||
</step>
|
||||
</workflow>
|
||||
</example>
|
||||
<example name="documentation_review_example">
|
||||
<scenario>
|
||||
Review a user-provided documentation section for accuracy against the codebase
|
||||
and provide recommendations for improvement in the chat.
|
||||
</scenario>
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>User provides documentation for review</description>
|
||||
<user_input>
|
||||
"Here's our current draft for the JWT_SECRET setting. Can you check it for accuracy? 'The `JWT_SECRET` is an optional key for enhancing security.'"
|
||||
</user_input>
|
||||
</step>
|
||||
<step number="2">
|
||||
<description>Analyze relevant code</description>
|
||||
<tool_use><![CDATA[
|
||||
<codebase_search>
|
||||
<query>JWT_SECRET configuration implementation</query>
|
||||
</codebase_search>
|
||||
]]></tool_use>
|
||||
<expected_findings>
|
||||
- Code where `JWT_SECRET` is read (e.g., `process.env.JWT_SECRET`)
|
||||
- Logic that fails if the secret is missing
|
||||
- Default values or error handling related to the secret
|
||||
</expected_findings>
|
||||
</step>
|
||||
<step number="3">
|
||||
<description>Formulate and provide feedback in chat</description>
|
||||
<tool_use><![CDATA[
|
||||
<attempt_completion>
|
||||
<result>
|
||||
I have reviewed the documentation section provided for the `JWT_SECRET` setting. Here are my recommendations for improvement:
|
||||
|
||||
**Overall Assessment**: The current draft is critically inaccurate and could lead to security vulnerabilities if followed.
|
||||
|
||||
**Recommendations for Improvement**:
|
||||
|
||||
* **Critical Inaccuracy**:
|
||||
* The documentation states that `JWT_SECRET` is optional. However, the application will fail to start if it is not provided. It is a **required** setting for the application to function securely.
|
||||
* **Suggestion**: "The `JWT_SECRET` is a **required** environment variable used to sign and verify JSON Web Tokens. The application will not run without it."
|
||||
|
||||
This feedback can be copied and pasted for your documentation team.
|
||||
</result>
|
||||
</attempt_completion>
|
||||
]]></tool_use>
|
||||
<note>No file is written. The feedback is provided directly to the user in the chat interface.</note>
|
||||
</step>
|
||||
</workflow>
|
||||
</example>
|
||||
|
||||
<best_practices>
|
||||
<practice name="comprehensive_coverage">
|
||||
<description>Ensure all aspects are documented</description>
|
||||
<checklist>
|
||||
<item>Technical implementation details</item>
|
||||
<item>Business logic and rules</item>
|
||||
<item>User workflows and journeys</item>
|
||||
<item>API specifications</item>
|
||||
<item>Configuration options</item>
|
||||
<item>Security measures</item>
|
||||
<item>Performance characteristics</item>
|
||||
<item>Error handling</item>
|
||||
<item>Testing strategies</item>
|
||||
<item>Deployment procedures</item>
|
||||
</checklist>
|
||||
</practice>
|
||||
|
||||
<practice name="multi_audience_writing">
|
||||
<description>Tailor content for different readers</description>
|
||||
<audiences>
|
||||
<audience type="end_users">
|
||||
Focus on how-to guides and troubleshooting
|
||||
</audience>
|
||||
<audience type="developers">
|
||||
Include code examples and technical details
|
||||
</audience>
|
||||
<audience type="administrators">
|
||||
Emphasize configuration and maintenance
|
||||
</audience>
|
||||
<audience type="stakeholders">
|
||||
Highlight business value and metrics
|
||||
</audience>
|
||||
</audiences>
|
||||
</practice>
|
||||
|
||||
<practice name="maintainable_documentation">
|
||||
<description>Create documentation that's easy to update</description>
|
||||
<guidelines>
|
||||
<guideline>Use clear section headers</guideline>
|
||||
<guideline>Include version information</guideline>
|
||||
<guideline>Add last-updated timestamps</guideline>
|
||||
<guideline>Cross-reference related sections</guideline>
|
||||
<guideline>Provide migration guides</guideline>
|
||||
</guidelines>
|
||||
</practice>
|
||||
|
||||
<practice name="example_driven">
|
||||
<description>Include practical examples throughout</description>
|
||||
<example_types>
|
||||
<type>Code snippets with syntax highlighting</type>
|
||||
<type>API request/response pairs</type>
|
||||
<type>Configuration examples</type>
|
||||
<type>Command-line usage</type>
|
||||
<type>Error scenarios and solutions</type>
|
||||
</example_types>
|
||||
</practice>
|
||||
</best_practices>
|
||||
|
||||
<output_validation>
|
||||
<checklist>
|
||||
<item>Table of contents with working links</item>
|
||||
<item>All sections properly formatted</item>
|
||||
<item>Code examples are syntactically correct</item>
|
||||
<item>No placeholder text remaining</item>
|
||||
<item>Version information included</item>
|
||||
<item>Cross-references are valid</item>
|
||||
<item>Metadata is complete</item>
|
||||
<item>File follows naming convention</item>
|
||||
</checklist>
|
||||
</output_validation>
|
||||
</complete_extraction_examples>
|
||||
323
.roo/rules-docs-extractor/6_communication_guidelines.xml
Normal file
323
.roo/rules-docs-extractor/6_communication_guidelines.xml
Normal file
|
|
@ -0,0 +1,323 @@
|
|||
<communication_guidelines>
|
||||
<overview>
|
||||
Guidelines for communicating with users and formatting documentation output
|
||||
during the extraction process.
|
||||
</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>
|
||||
|
||||
<clarification_only_when_needed>
|
||||
<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>
|
||||
</when_to_ask>
|
||||
|
||||
<question_example><![CDATA[
|
||||
<ask_followup_question>
|
||||
<question>I found multiple authentication systems. Which one should I document?</question>
|
||||
<follow_up>
|
||||
<suggest>JWT-based authentication 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>
|
||||
</follow_up>
|
||||
</ask_followup_question>
|
||||
]]></question_example>
|
||||
</clarification_only_when_needed>
|
||||
|
||||
<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>
|
||||
</when_to_update>
|
||||
|
||||
<update_format>
|
||||
<template>
|
||||
Analyzing [component/feature]...
|
||||
- Found [X] files related to [feature]
|
||||
- Identified [Y] API endpoints
|
||||
- Discovered [Z] configuration options
|
||||
</template>
|
||||
</update_format>
|
||||
</progress_updates>
|
||||
|
||||
<findings_communication>
|
||||
<important_discoveries>
|
||||
<discovery type="security_issue">
|
||||
Alert user to potential security concerns found during analysis
|
||||
</discovery>
|
||||
<discovery type="deprecated_code">
|
||||
Note deprecated features that need migration documentation
|
||||
</discovery>
|
||||
<discovery type="missing_documentation">
|
||||
Highlight areas where code lacks inline documentation
|
||||
</discovery>
|
||||
<discovery type="complex_dependencies">
|
||||
Warn about intricate dependency chains affecting the feature
|
||||
</discovery>
|
||||
</important_discoveries>
|
||||
<review_findings>
|
||||
<template><![CDATA[
|
||||
I have reviewed the documentation section provided. Here are my recommendations for improvement:
|
||||
|
||||
**Overall Assessment**: [Brief summary of the document's quality]
|
||||
|
||||
**Recommendations for Improvement**:
|
||||
|
||||
* **Critical Inaccuracies**:
|
||||
* [Inaccuracy 1]: The documentation states [X], but the code implements [Y].
|
||||
* [Inaccuracy 2]: ...
|
||||
|
||||
* **Major Omissions**:
|
||||
* The documentation is missing information about [Missing Feature/Concept].
|
||||
* ...
|
||||
|
||||
* **Suggestions for Clarity**:
|
||||
* The section on [Topic] could be clarified by [Suggestion].
|
||||
* ...
|
||||
|
||||
This feedback can be copied and pasted for your documentation team.
|
||||
]]></template>
|
||||
</review_findings>
|
||||
</findings_communication>
|
||||
</user_interaction>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<example><![CDATA[
|
||||
```typescript
|
||||
// src/auth/auth.service.ts
|
||||
export class AuthService {
|
||||
async validateUser(email: string, password: string): Promise<User> {
|
||||
// Implementation
|
||||
}
|
||||
}
|
||||
```
|
||||
]]></example>
|
||||
</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>
|
||||
<example><![CDATA[
|
||||
| Variable | Type | Default | Description |
|
||||
|----------|------|---------|-------------|
|
||||
| `JWT_SECRET` | string | - | Secret key for JWT signing |
|
||||
| `JWT_EXPIRATION` | string | '15m' | Token expiration time |
|
||||
]]></example>
|
||||
</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>
|
||||
</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>
|
||||
</internal_links>
|
||||
|
||||
<external_links>
|
||||
<format>[Link text](https://example.com)</format>
|
||||
<rule>Use HTTPS when available</rule>
|
||||
<rule>Link to official documentation</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>
|
||||
</file_references>
|
||||
</cross_references>
|
||||
|
||||
<special_sections>
|
||||
<alerts>
|
||||
<type name="warning">
|
||||
<format>> ⚠️ **Warning**: [message]</format>
|
||||
<use_for>Security concerns, breaking changes, deprecations</use_for>
|
||||
</type>
|
||||
<type name="note">
|
||||
<format>> 📝 **Note**: [message]</format>
|
||||
<use_for>Important information, clarifications</use_for>
|
||||
</type>
|
||||
<type name="tip">
|
||||
<format>> 💡 **Tip**: [message]</format>
|
||||
<use_for>Best practices, optimization suggestions</use_for>
|
||||
</type>
|
||||
</alerts>
|
||||
|
||||
<metadata_blocks>
|
||||
<version_info><![CDATA[
|
||||
---
|
||||
Feature: Authentication System
|
||||
Version: 2.1.0
|
||||
Last Updated: 2024-01-15
|
||||
Status: Stable
|
||||
---
|
||||
]]></version_info>
|
||||
</metadata_blocks>
|
||||
</special_sections>
|
||||
</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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
</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>
|
||||
</structure>
|
||||
|
||||
<example><![CDATA[
|
||||
I've completed the comprehensive documentation extraction for the authentication system.
|
||||
|
||||
**Documentation Generated**: `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
|
||||
|
||||
**Coverage**:
|
||||
- ✅ Technical implementation details
|
||||
- ✅ API reference with examples
|
||||
- ✅ Configuration guide
|
||||
- ✅ Security considerations
|
||||
- ✅ User and developer guides
|
||||
- ✅ Troubleshooting section
|
||||
|
||||
The documentation is structured for multiple audiences and includes all requested metadata, version information, and cross-references.
|
||||
]]></example>
|
||||
<example_review><![CDATA[
|
||||
I have completed the review of the provided documentation section.
|
||||
|
||||
**Action Taken**:
|
||||
- Analyzed the provided text against the current codebase for accuracy.
|
||||
- Identified several areas for improvement and outlined them as a recommendation.
|
||||
|
||||
**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.
|
||||
]]></example_review>
|
||||
</completion_message>
|
||||
|
||||
<error_handling>
|
||||
<common_scenarios>
|
||||
<scenario type="feature_not_found">
|
||||
<response>
|
||||
I couldn't find a feature matching "[feature name]". Here are some similar features I found:
|
||||
- [List similar features]
|
||||
Would you like me to document one of these instead?
|
||||
</response>
|
||||
</scenario>
|
||||
|
||||
<scenario type="insufficient_code_documentation">
|
||||
<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
|
||||
</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
|
||||
</response>
|
||||
</scenario>
|
||||
</common_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>
|
||||
</before_completion>
|
||||
</quality_checks>
|
||||
</communication_guidelines>
|
||||
254
.roo/rules-docs-extractor/7_user_friendly_examples.xml
Normal file
254
.roo/rules-docs-extractor/7_user_friendly_examples.xml
Normal file
|
|
@ -0,0 +1,254 @@
|
|||
<user_friendly_examples>
|
||||
<overview>
|
||||
Examples and patterns for creating documentation that prioritizes user experience
|
||||
and practical understanding over technical completeness.
|
||||
</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>
|
||||
|
||||
<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>
|
||||
</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>
|
||||
|
||||
<principle name="conversational_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>
|
||||
</principle>
|
||||
</writing_principles>
|
||||
|
||||
<structure_examples>
|
||||
<example name="feature_introduction">
|
||||
<template><![CDATA[
|
||||
# [Feature Name]
|
||||
|
||||
[One-sentence description of what it does for the user]
|
||||
|
||||
### Key Features
|
||||
- [Benefit 1 - what users can do]
|
||||
- [Benefit 2 - what problem it solves]
|
||||
- [Benefit 3 - how it makes life easier]
|
||||
|
||||
---
|
||||
]]></template>
|
||||
</example>
|
||||
|
||||
<example name="why_it_matters">
|
||||
<template><![CDATA[
|
||||
## Why This Matters
|
||||
|
||||
**Without [feature]**: [Description of the painful old way]
|
||||
- [Specific pain point]
|
||||
- [Another pain point]
|
||||
- [Time/effort wasted]
|
||||
|
||||
**With [feature]**: [Description of the better experience]
|
||||
]]></template>
|
||||
</example>
|
||||
|
||||
<example name="configuration_section">
|
||||
<template><![CDATA[
|
||||
## Configuration
|
||||
|
||||
You can customize this feature in Roo's 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]
|
||||
|
||||
2. **[Another setting]**
|
||||
- What it does: [Plain language explanation]
|
||||
- Default: [Default value]
|
||||
- Try changing this if: [Specific use case]
|
||||
]]></template>
|
||||
</example>
|
||||
|
||||
<example name="common_questions">
|
||||
<template><![CDATA[
|
||||
## Common Questions
|
||||
|
||||
**"[Actual question users ask]"**
|
||||
[Direct, helpful answer]
|
||||
[Optional: Additional tip or context]
|
||||
|
||||
**"[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]
|
||||
]]></template>
|
||||
</example>
|
||||
|
||||
<example name="troubleshooting">
|
||||
<template><![CDATA[
|
||||
## Troubleshooting
|
||||
|
||||
### [Problem symptom users would recognize]
|
||||
**What's happening**: [Brief explanation]
|
||||
**Quick fix**: [Immediate solution]
|
||||
**If that doesn't work**: [Alternative solution]
|
||||
|
||||
### [Another common issue]
|
||||
**You might see this when**: [Scenario]
|
||||
**Solution**:
|
||||
1. [First step]
|
||||
2. [Second step]
|
||||
3. [If needed, third step]
|
||||
]]></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">
|
||||
<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>
|
||||
</example>
|
||||
|
||||
<example context="describing an 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>
|
||||
</example>
|
||||
|
||||
<example context="explaining a 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>
|
||||
</example>
|
||||
</friendly_explanations>
|
||||
|
||||
<visual_elements>
|
||||
<use_emojis_sparingly>
|
||||
<when>Error messages: ⚠️</when>
|
||||
<when>Tips: 💡</when>
|
||||
<when>Important notes: 📝</when>
|
||||
<when>Security: 🔒</when>
|
||||
</use_emojis_sparingly>
|
||||
|
||||
<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>
|
||||
</tone_examples>
|
||||
|
||||
<real_world_example>
|
||||
<title>Concurrent File Reads Documentation</title>
|
||||
<content>< tool automatically accepts multiple files in a single request.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
You can customize this feature 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
|
||||
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
- **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
|
||||
|
||||
## Common Questions
|
||||
|
||||
**"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
|
||||
|
||||
**"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>Are sections short and scannable?</item>
|
||||
<item>Does it answer common user questions?</item>
|
||||
<item>Is help easily accessible?</item>
|
||||
</checklist>
|
||||
</user_friendly_examples>
|
||||
15
.roomodes
15
.roomodes
|
|
@ -198,3 +198,18 @@ customModes:
|
|||
- mcp
|
||||
- command
|
||||
source: project
|
||||
|
||||
- slug: docs-extractor
|
||||
name: 📚 Docs Extractor
|
||||
roleDefinition: >-
|
||||
You are Roo, a comprehensive documentation extraction specialist focused on analyzing and documenting all technical and non-technical information about features and components within codebases.
|
||||
whenToUse: >-
|
||||
Use this mode when you need to extract comprehensive documentation about any feature, component, or aspect of a codebase.
|
||||
groups:
|
||||
- read
|
||||
- - edit
|
||||
- fileRegex: (DOCS-TEMP-.*\.md$|\.roo/docs-extractor/.*\.md$)
|
||||
description: Temporary documentation extraction files only
|
||||
- command
|
||||
- mcp
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue