organize structure for .roo and for ai in general

rework rulels
2026-04-23 03:36:37 +00:00 · 2025-12-10 19:59:13 +02:00
parent 749c8e674d
commit 8a284eb106
84 changed files with 3044 additions and 35 deletions
@@ -0,0 +1,82 @@
+# Decompose
+
+## Initial data:
+ - Problem description: `@_docs/00_problem/problem_description.md`
+ - Input data: `@_docs/00_problem/input_data`. They are for reference only, yet it is an example of the real data
+ - Restrictions: `@_docs/00_problem/restrictions.md`
+ - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`
+ - Security approach: `@_docs/00_problem/security_approach.md`
+ - Full Solution Description: `@_docs/01_solution/solution.md`
+
+## Role
+  You are a professional software architect
+
+## Task
+ - Read problem description and solution draft, analyze it thoroughly
+ - Decompose a complex system solution to the components with proper communications between them, so that system would solve the problem. 
+ - Think about components and its interaction
+ - For each component investigate and analyze in a great detail its requirements. If additional components are needed, like data preparation, create them
+ - Solution draft could be incomplete, so add all necessary components to meet acceptance criteria and restrictions
+ - When you've got full understanding of how exactly each component will interact with each other, create components
+
+## Output Format
+
+### Components Decomposition
+
+Store description of each component to the file `_docs/02_components/[##]_[component_name]/[##]._component_[component_name].md` with the next structure:
+    1. High-level overview
+        - **Purpose:** A concise summary of what this component does and its role in the larger system.
+        - **Architectural Pattern:** Identify the design patterns used (e.g., Singleton, Observer, Factory).
+    2. API Reference. Create a table for each function or method with the next columns:
+        - Name
+        - Description
+        - Input
+        - Output
+        - Description of input and output data in case if it is not obvious
+        - Test cases which could be for the method
+    3. Implementation Details
+        - **Algorithmic Complexity:** Analyze Time (Big O) and Space complexity for critical methods.
+        - **State Management:** Explain how this component handles state (local vs. global).
+        - **Dependencies:** List key external libraries and their purpose here.
+        - **Error Handling:** Define error handling strategy for this component.
+    4. Tests
+        - Integration tests for the component if needed.
+        - Non-functional tests for the component if needed.
+    5. Extensions and Helpers
+        - Store Extensions and Helpers to support functionality across multiple components to a separate folder `_docs/02_components/helpers`.
+    6. Caveats & Edge Cases
+      - Known limitations
+      - Potential race conditions
+      - Potential performance bottlenecks.
+
+### Dependency Graph
+ - Create component dependency graph showing implementation order
+ - Identify which components can be implemented in parallel
+
+### API Contracts
+ - Define interfaces/contracts between components
+ - Specify data formats exchanged
+
+### Logging Strategy
+ - Define global logging approach for the system
+ - Log levels, format, storage
+
+For the whole system make these diagrams and store them to `_docs/02_components`:
+
+### Logic & Architecture
+    - Generate draw.io components diagrams shows relations between components.
+        - Make sure lines are not intersect each other, or at least try to minimize intersections.
+        - Group the semantically coherent components into the groups
+        - Leave enough space for the nice alignment of the components boxes
+        - Put external users of the system closer to those components' blocks they are using
+
+    - Generate a Mermaid Flowchart diagrams for each of the main control flows
+        - Create multiple flows system can operate, and generate a flowchart diagram per each flow
+        - Flows can relate to each other
+
+## Notes
+ - Strongly follow Single Responsibility Principle during creation of components.
+ - Follow dumb code - smart data principle. Do not overcomplicate
+ - Components should be semantically coherent. Do not spread similar functionality across multiple components
+ - Do not put any code yet, only names, input and output.
+ - Ask as many questions as possible to clarify all uncertainties.
@@ -0,0 +1,30 @@
+# Component Assessment
+
+## Initial data:
+ - Problem description: `@_docs/00_problem/problem_description.md`
+ - Input data: `@_docs/00_problem/input_data`. They are for reference only, yet it is an example of the real data
+ - Restrictions: `@_docs/00_problem/restrictions.md`
+ - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`
+ - Security approach: `@_docs/00_problem/security_approach.md`
+ - Full Solution Description: `@_docs/01_solution/solution.md`
+
+## Role
+    You are a professional software architect
+
+## Task
+    - Read carefully all the documents above
+    - Check all the components @02_components how coherent they are
+    - Follow interaction logic and flows, try to find some potential problems there
+    - Try to find some missing interaction or circular dependencies
+    - Check all the components follows Single Responsibility Principle
+    - Check all the follows dumb code - smart data principle. So that resulting code shouldn't be overcomplicated
+    - Check for security vulnerabilities in component design
+    - Check for performance bottlenecks
+    - Verify API contracts are consistent across components
+
+## Output
+    Form a list of problems with fixes in the next format:
+    - Component
+    - Problem type (Architectural/Security/Performance/API)
+    - Problem, reason
+    - Fix or potential fixes
@@ -0,0 +1,36 @@
+# Security Check
+
+## Initial data:
+ - Problem description: `@_docs/00_problem/problem_description.md`
+ - Restrictions: `@_docs/00_problem/restrictions.md`
+ - Security approach: `@_docs/00_problem/security_approach.md`
+ - Full Solution Description: `@_docs/01_solution/solution.md`
+ - Components: `@_docs/02_components`
+
+## Role
+  You are a security architect
+
+## Task
+ - Review each component against security requirements
+ - Identify security gaps in component design
+ - Verify security controls are properly distributed across components
+ - Check for common vulnerabilities (injection, auth bypass, data leaks)
+
+## Output
+  ### Security Assessment per Component
+   For each component:
+   - Component name
+   - Security gaps found
+   - Required security controls
+   - Priority (High/Medium/Low)
+
+  ### Cross-Component Security
+   - Authentication flow assessment
+   - Authorization gaps
+   - Data flow security (encryption in transit/at rest)
+   - Logging for security events
+
+  ### Recommendations
+   - Required changes before implementation
+   - Security helpers/components to add
+
@@ -0,0 +1,67 @@
+# Generate Jira Epics
+
+## Initial data:
+ - Problem description: `@_docs/00_problem/problem_description.md`
+ - Input data: `@_docs/00_problem/input_data`. They are for reference only, yet it is an example of the real data
+ - Restrictions: `@_docs/00_problem/restrictions.md`
+ - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`
+ - Full Solution Description: `@_docs/01_solution/solution.md`
+ - Components: `@_docs/02_components`
+
+## Role
+  You are a world class product manager
+
+## Task
+  - Generate Jira Epics from the Components using Jira MCP
+  - Order epics by dependency (which must be done first)
+  - Include rough effort estimation per epic
+  - Ensure each epic has clear goal and acceptance criteria, verify it with acceptance criteria
+  - Generate draw.io components diagram based on previous diagram shows relations between components and current Jira Epic number, corresponding to each component.
+
+## Output
+ Epic format: 
+ - Epic Name [Component] – [Outcome]
+   - Example: Data Ingestion – Near-real-time pipeline
+ - Epic Summary (1–2 sentences)
+   - What we are building + why it matters
+ - Problem / Context
+   - Current state, pain points, constraints, business opportunities, Links to architecture decision records or diagrams
+ - Scope. Detailed description
+  - In Scope. Bullet list of capabilities (not tasks)
+  - Out-of-scope. Explicit exclusions to prevent scope creep
+ - Assumptions
+  - System design specifics, input material quality, data structures, network availability etc
+ - Dependencies
+  - Other epics that must be completed first
+  - Other components, services, hardware, environments, certificates, data sources etc.
+ - Effort Estimation
+  - T-shirt size (S/M/L/XL) or story points range
+ - Users / Consumers
+  - Internal, External, Systems, Short list of the key use cases.
+ - Requirements
+  - Functional - API expectations, events, data handling, idempotency, retry behavior etc
+  - Non-functional - Availability, latency, throughput, scalability, processing limits, data retention etc
+  - Security/Compliance - Authentication, encryption, secrets, logging, SOC2/ISO if applicable
+ - Design & Architecture (links)
+  - High-level diagram link, Data flow, sequence diagrams, schemas etc
+ - Definition of Done (Epic-level)
+  - Feature list per epic scope
+  - Automated tests (unit/integration/e2e) + minimum coverage threshold met
+  - Runbooks if applicable
+  - Documentation updated
+ - Acceptance Criteria (measurable)
+ - Risks & Mitigations
+  - Top 5 risks (technical + delivery) with mitigation owners or systems involved
+ - Label epic
+  - component:<name>
+  - env:prod|stg
+  - type:platform|data|integration
+
+ - Jira Issue Breakdown
+   - Create consistent child issues under the epic
+   - Spikes
+   - Tasks
+   - Technical enablers
+  
+## Notes
+ - Be as much concise as possible in formulating epics. The less words with the same meaning - the better epic is.
@@ -0,0 +1,57 @@
+# Data Model Design
+
+## Initial data:
+ - Problem description: `@_docs/00_problem/problem_description.md`
+ - Restrictions: `@_docs/00_problem/restrictions.md`
+ - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`
+ - Full Solution Description: `@_docs/01_solution/solution.md`
+ - Components: `@_docs/02_components`
+
+## Role
+  You are a professional database architect
+
+## Task
+ - Analyze solution and components to identify all data entities
+ - Design database schema that supports all component requirements
+ - Define relationships, constraints, and indexes
+ - Consider data access patterns for query optimization
+ - Plan for data migration if applicable
+
+## Output
+
+### Entity Relationship Diagram
+ - Create ERD showing all entities and relationships
+ - Use Mermaid or draw.io format
+
+### Schema Definition
+For each entity:
+ - Table name
+ - Columns with types, constraints, defaults
+ - Primary keys
+ - Foreign keys and relationships
+ - Indexes (clustered, non-clustered)
+ - Partitioning strategy (if needed)
+
+### Data Access Patterns
+ - List common queries per component
+ - Identify hot paths requiring optimization
+ - Recommend caching strategy
+
+### Migration Strategy
+ - Initial schema creation scripts
+ - Seed data requirements
+ - Rollback procedures
+
+### Storage Estimates
+ - Estimated row counts per table
+ - Storage requirements
+ - Growth projections
+
+Store output to `_docs/02_components/data_model.md`
+
+## Notes
+ - Follow database normalization principles (3NF minimum)
+ - Consider read vs write optimization based on access patterns
+ - Plan for horizontal scaling if required
+ - Ask questions to clarify data requirements
+
@@ -0,0 +1,64 @@
+# API Contracts Design
+
+## Initial data:
+ - Problem description: `@_docs/00_problem/problem_description.md`
+ - Restrictions: `@_docs/00_problem/restrictions.md`
+ - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`
+ - Full Solution Description: `@_docs/01_solution/solution.md`
+ - Components: `@_docs/02_components`
+ - Data Model: `@_docs/02_components/data_model.md`
+
+## Role
+  You are a professional API architect
+
+## Task
+ - Define API contracts between all components
+ - Specify external API endpoints (if applicable)
+ - Define data transfer objects (DTOs)
+ - Establish error response standards
+ - Plan API versioning strategy
+
+## Output
+
+### Internal Component Interfaces
+For each component boundary:
+ - Interface name
+ - Methods with signatures
+ - Input/Output DTOs
+ - Error types
+ - Async/Sync designation
+
+### External API Specification
+Generate OpenAPI/Swagger spec including:
+ - Endpoints with HTTP methods
+ - Request/Response schemas
+ - Authentication requirements
+ - Rate limiting rules
+ - Example requests/responses
+
+### DTO Definitions
+For each data transfer object:
+ - Name and purpose
+ - Fields with types
+ - Validation rules
+ - Serialization format (JSON, Protobuf, etc.)
+
+### Error Contract
+ - Standard error response format
+ - Error codes and messages
+ - HTTP status code mapping
+
+### Versioning Strategy
+ - API versioning approach (URL, header, query param)
+ - Deprecation policy
+ - Breaking vs non-breaking change definitions
+
+Store output to `_docs/02_components/api_contracts.md`
+Store OpenAPI spec to `_docs/02_components/openapi.yaml` (if applicable)
+
+## Notes
+ - Follow RESTful conventions for external APIs
+ - Keep internal interfaces minimal and focused
+ - Design for backward compatibility
+ - Ask questions to clarify integration requirements
+
@@ -0,0 +1,59 @@
+# Generate Tests
+
+## Initial data:
+ - Problem description: `@_docs/00_problem/problem_description.md`
+ - Input data: `@_docs/00_problem/input_data`. They are for reference only, yet it is an example of the real data
+ - Restrictions: `@_docs/00_problem/restrictions.md`
+ - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`
+ - Security approach: `@_docs/00_problem/security_approach.md`
+ - Full Solution Description: `@_docs/01_solution/solution.md`
+
+## Role
+  You are a professional Quality Assurance Engineer
+
+## Task
+ - Compose tests according to the test strategy
+ - Cover all the criteria with tests specs
+ - Minimum coverage target: 75%
+
+## Output
+ Store all tests specs to the files `_docs/02_tests/[##]_[test_name]_spec.md`
+ Types and structures of tests:
+
+ - Integration tests
+   - Summary
+   - Detailed description
+   - Input data for this specific test scenario
+   - Expected result
+   - Maximum expected time to get result
+
+ - Performance tests
+   - Summary
+   - Load/stress scenario description
+   - Expected throughput/latency
+   - Resource limits
+
+ - Security tests
+   - Summary
+   - Attack vector being tested
+   - Expected behavior
+   - Pass/Fail criteria
+ 
+ - Acceptance tests
+   - Summary
+   - Detailed description
+   - Preconditions for tests
+   - Steps:
+     - Step1 - Expected result1
+     - Step2 - Expected result2  
+     ...
+     - StepN - Expected resultN
+
+ - Test Data Management
+   - Required test data
+   - Setup/Teardown procedures
+   - Data isolation strategy
+
+## Notes
+  - Do not put any code yet
+  - Ask as many questions as needed.
@@ -0,0 +1,111 @@
+# Risk Assessment
+
+## Initial data:
+ - Problem description: `@_docs/00_problem/problem_description.md`
+ - Restrictions: `@_docs/00_problem/restrictions.md`
+ - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`
+ - Full Solution Description: `@_docs/01_solution/solution.md`
+ - Components: `@_docs/02_components`
+ - Estimation: `@_docs/02_components/estimation.md`
+
+## Role
+  You are a technical risk analyst
+
+## Task
+ - Identify technical and project risks
+ - Assess probability and impact
+ - Define mitigation strategies
+ - Create risk monitoring plan
+
+## Output
+
+### Risk Register
+
+| ID | Risk | Category | Probability | Impact | Score | Mitigation | Owner |
+|----|------|----------|-------------|--------|-------|------------|-------|
+| R1 | | Tech/Schedule/Resource/External | High/Med/Low | High/Med/Low | H/M/L | | |
+
+### Risk Scoring Matrix
+
+|  | Low Impact | Medium Impact | High Impact |
+|--|------------|---------------|-------------|
+| High Probability | Medium | High | Critical |
+| Medium Probability | Low | Medium | High |
+| Low Probability | Low | Low | Medium |
+
+### Risk Categories
+
+#### Technical Risks
+- Technology choices may not meet requirements
+- Integration complexity underestimated
+- Performance targets unachievable
+- Security vulnerabilities
+
+#### Schedule Risks
+- Scope creep
+- Dependencies delayed
+- Resource unavailability
+- Underestimated complexity
+
+#### Resource Risks
+- Key person dependency
+- Skill gaps
+- Team availability
+
+#### External Risks
+- Third-party API changes
+- Vendor reliability
+- Regulatory changes
+
+### Top Risks (Ranked)
+
+#### 1. [Highest Risk]
+- **Description**: 
+- **Probability**: High/Medium/Low
+- **Impact**: High/Medium/Low
+- **Mitigation Strategy**: 
+- **Contingency Plan**: 
+- **Early Warning Signs**: 
+- **Owner**: 
+
+#### 2. [Second Highest Risk]
+...
+
+### Risk Mitigation Plan
+
+| Risk ID | Mitigation Action | Timeline | Cost | Responsible |
+|---------|-------------------|----------|------|-------------|
+| R1 | | | | |
+
+### Risk Monitoring
+
+#### Review Schedule
+- Daily standup: Discuss blockers (potential risks materializing)
+- Weekly: Review risk register, update probabilities
+- Sprint end: Comprehensive risk review
+
+#### Early Warning Indicators
+| Risk | Indicator | Threshold | Action |
+|------|-----------|-----------|--------|
+| | | | |
+
+### Contingency Budget
+- Time buffer: 20% of estimated duration
+- Scope flexibility: [List features that can be descoped]
+- Resource backup: [Backup resources if available]
+
+### Acceptance Criteria for Risks
+Define which risks are acceptable:
+- Low risks: Accepted, monitored
+- Medium risks: Mitigation required
+- High risks: Mitigation + contingency required
+- Critical risks: Must be resolved before proceeding
+
+Store output to `_docs/02_components/risk_assessment.md`
+
+## Notes
+ - Update risk register throughout project
+ - Escalate critical risks immediately
+ - Consider both likelihood and impact
+ - Ask questions to uncover hidden risks
+
@@ -0,0 +1,40 @@
+# Generate Features for the provided component spec
+
+## Input parameters
+ - component_spec.md. Required. Do NOT proceed if it is NOT provided!
+ - parent Jira Epic in the format AZ-###. Required. Do NOT proceed if it is NOT provided!
+
+## Prerequisites
+ - Jira Epics must be created first (step 2.20)
+
+## Initial data:
+ - Problem description: `@_docs/00_problem/problem_description.md`
+ - Input data: `@_docs/00_problem/input_data`. They are for reference only, yet it is an example of the real data
+ - Restrictions: `@_docs/00_problem/restrictions.md`
+ - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`
+ - Full Solution Description: `@_docs/01_solution/solution.md`
+
+## Role
+  You are a professional software architect
+
+## Task
+ - Read very carefully component_spec.md
+ - Decompose component_spec.md to the features. If component is simple or atomic, then create only 1 feature.
+ - Split to the many features only if it necessary and would be easier to implement
+ - Do not create features of other components, create *only* features of this exact component
+ - Each feature should be atomic, could contain 0 API, or list of semantically connected APIs
+ - After splitting assess yourself
+ - Add complexity points estimation (1, 2, 3, 5, 8) per feature
+ - Note feature dependencies (some features may be independent)
+ - Use `@gen_feature_spec.md` as a complete guidance how to generate feature spec
+ - Generate Jira tasks per each feature using this spec `@gen_jira_task_and_branch.md` using Jira MCP.
+
+## Output
+ - The file name of the feature specs should follow this format: `[component's number ##].[feature's number ##]_feature_[feature_name].md`.
+ - The structure of the feature spec should follow this spec `@gen_feature_spec.md`
+ - The structure of the Jira task should follow this spec: `@gen_jira_task_and_branch.md`
+ - Include dependency notes (which features can be done in parallel)
+
+## Notes
+  - Do NOT generate any code yet, only brief explanations what should be done.  
+  - Ask as many questions as needed.