organize structure for .roo and for ai in general

rework rulels
2026-04-22 21:06:36 +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,189 @@
+# Generate Feature Specification
+Create a focused behavioral specification that describes **what** the system should do, not **how** it should be built.
+
+## Input parameter
+  building_block.md
+  Example: `_docs/iterative/building_blocks/01-dashboard-export-example.md`
+
+## Objective
+Generate lean specifications with:
+- Clear problem statement and desired outcomes
+- Behavioral acceptance criteria in Gherkin format
+- Essential non-functional requirements
+- Complexity estimation
+- Feature dependencies
+- No implementation prescriptiveness
+
+## Process
+1. Read the building_block.md
+2. Analyze the codebase to understand context
+3. Generate a behavioral specification using the structure below
+4. **DO NOT** include implementation details, file structures, or technical architecture
+5. Focus on behavior, user experience, and acceptance criteria
+6. Save the specification into `_docs/iterative/feature_specs/spec.md`
+   Example: `_docs/iterative/feature_specs/01-dashboard-export-example.md`
+
+## Specification Structure
+
+### Header
+```markdown
+# [Feature Name]
+
+**Status**: Draft | **Date**: [YYYY-MM-DD] | **Feature**: [Brief Feature Description]
+**Complexity**: [1|2|3|5|8] points
+**Dependencies**: [List dependent features or "None"]
+```
+
+### Problem
+Clear, concise statement of the problem users are facing.
+
+### Outcome
+Measurable or observable goals/benefits (use bullet points).
+
+### Scope
+#### Included
+What's in scope for this feature (bullet points).
+#### Excluded
+Explicitly what's **NOT** in scope (bullet points).
+
+### Acceptance Criteria
+Each acceptance criterion should be:
+- Numbered sequentially (AC-1, AC-2, etc.)
+- Include a brief title
+- Written in Gherkin format (Given/When/Then)
+
+Example:
+  **AC-1: Export Availability**
+  Given the user is viewing the dashboard
+  When the dashboard loads
+  Then an "Export to Excel" button should be visible in the filter/actions area
+
+### Non-Functional Requirements
+Only include essential non-functional requirements:
+- Performance (if relevant)
+- Compatibility (if relevant)
+- Reliability (if relevant)
+
+Use sub-sections with bullet points.
+
+### Unit tests based on Acceptance Criteria
+ - Acceptance criteria references
+ - What should be tested
+ - Required outcome
+
+### Integration tests based on Acceptance Criteria and/or Non-Functional requirements
+ - Acceptance criteria references
+ - Initial data and conditions
+ - What should be tested
+ - How system should behave
+ - List of Non-functional requirements to be met
+
+### Constraints
+
+High-level constraints that guide implementation:
+- Architectural patterns (if critical)
+- Technical limitations
+- Integration requirements
+- No breaking changes (if applicable)
+
+### Risks & Mitigation
+
+List key risks with mitigation strategies (if applicable).
+
+Each risk should have:
+- *Risk*: Description
+- *Mitigation*: Approach
+
+## Complexity Points Guide
+- 1 point: Trivial, self-contained, no dependencies
+- 2 points: Non-trivial, low complexity, minimal coordination
+- 3 points: Multi-step, moderate complexity, potential alignment needed
+- 5 points: Difficult, interconnected logic, medium-high risk
+- 8 points: High ambiguity, multiple components, very high risk (consider splitting)
+
+## Output Guidelines
+**DO:**
+- Focus on behavior and user experience
+- Use clear, simple language
+- Keep acceptance criteria testable
+- Include realistic scope boundaries
+- Write from the user's perspective
+- Include complexity estimation
+- Note dependencies on other features
+
+**DON'T:**
+- Include implementation details (file paths, classes, methods)
+- Prescribe technical solutions or libraries
+- Add architectural diagrams or code examples
+- Specify exact API endpoints or data structures
+- Include step-by-step implementation instructions
+- Add "how to build" guidance
+
+
+
+## Example
+
+```markdown
+# Dashboard Export to Excel
+
+**Status**: Draft | **Date**: 2025-01-XX | **Feature**: Export Dashboard Data to Excel
+
+## Problem
+
+Users currently have no efficient way to export dashboard data for offline analysis, reporting, or sharing. Manual copy-paste is time-consuming, error-prone, and lacks context about active filters.
+
+## Outcome
+- Eliminate manual copy-paste workflows
+- Enable accurate data sharing with proper context
+- Measurable time savings (target: <30s vs. several minutes)
+- Improved data consistency for offline analysis
+
+## Scope
+### Included
+- Export filtered dashboard data to Excel
+- Single-click export from dashboard view
+- Respect all active filters (status, date range)
+### Excluded
+- CSV or PDF export options
+- Scheduled or automated exports
+- Email export functionality
+
+## Acceptance Criteria
+**AC-1: Export Button Visibility**
+Given the user is viewing the dashboard
+When the dashboard loads
+Then an "Export to Excel" button should be visible in the actions area
+
+**AC-2: Basic Export Functionality**
+Given the user is viewing the dashboard with data
+When the user clicks the "Export to Excel" button
+Then an Excel file should download to their default location
+And the filename should include a timestamp
+
+## Non-Functional Requirements
+
+**Performance**
+- Export completes in <2 seconds for up to 1000 records
+- Support up to 10,000 records per export
+
+**Compatibility**
+- Excel files openable in Microsoft Excel, Google Sheets, and LibreOffice
+- Standard Excel format (.xlsx)
+
+## Constraints
+- Must respect all currently active filters
+- Must follow existing hexagonal architecture patterns
+- No breaking changes to existing functionality
+
+## Risks & Mitigation
+**Risk 1: Excel File Compatibility**
+- *Risk*: Generated files don't open correctly in all spreadsheet applications
+- *Mitigation*: Use standard Excel format, test with multiple applications
+```
+
+## Implementation Notes
+- Use descriptive but concise titles
+- Keep specifications focused and scoped appropriately
+- Remember: This is a **behavioral spec**, not an implementation plan
+
+**CRITICAL**: Generate the spec file ONLY. Do NOT modify code, create files, or make any implementation changes at this stage.
@@ -0,0 +1,81 @@
+# Generate Jira Task and Git Branch from Spec
+Create a Jira ticket from a specification and set up git branch for development.
+
+## Inputs
+ - feature_spec.md (required): path to the source spec file. 
+  Example: `@_docs/iterative/feature_specs/spec-export-e2e.md`
+
+ - epic <Epic-Id> (required for Jira task creation): create Jira task under parent epic
+  Example: /gen_jira_task_and_branch @_docs/iterative/feature_specs/spec.md epic AZ-112
+
+ - update <Task-Id> (required for Jira task update): update existing Jira task
+  Example: /gen_jira_task_and_branch @_docs/iterative/feature_specs/spec.md update AZ-151
+
+## Objective
+1. Parse the spec to extract **Title**, **Description**, **Acceptance Criteria**, **Technical Details**, **Estimation**.  
+2. Create a Jira Task under Epic or Update existing Jira Task using **Jira MCP**
+3. Create git branch for the task
+
+## Parsing Rules
+
+### Title
+Use the first header at the top of the spec.
+
+### Description (Markdown ONLY — no AC/Tech here)
+Build from:
+- **Purpose & Outcomes → Intent** (bullets)
+- **Purpose & Outcomes → Success Signals** (bullets)
+- (Optional) one-paragraph summary from **Behavior Change → New Behavior**
+> **Do not include** Acceptance Criteria or Technical Details in Description if those fields exist in Jira.
+
+### Estimation
+Extract complexity points from spec header and add to Jira task.
+
+### Acceptance Criteria (Gherkin HTML)
+From **"Acceptance Criteria (Gherkin)"**, extract the **full Gherkin scenarios** including:
+- The `Feature:` line
+- Each complete `Scenario:` block with all `Given`, `When`, `Then`, `And` steps
+- Convert the entire Gherkin text to **HTML format** preserving structure
+- Do NOT create a simple checklist; keep the full Gherkin syntax for test traceability.
+
+### Technical Details
+Bullets composed of:
+- **Inputs → Key constraints**
+- **Scope → Included/Excluded** (condensed)
+- **Interfaces & Contracts** (names only — UI actions, endpoint names, event names)
+
+## Steps (Agent)
+
+1. **Check current branch**
+   - Verify user is on `dev` branch
+   - If not on `dev`, notify user: "Please switch to the dev branch before proceeding"
+   - Stop execution if not on dev
+
+2. Parse **Title**, **Description**, **AC**, **Tech**, **Estimation** per **Parsing Rules**.
+
+3. **Create** or **Update** the Jira Task with the field mapping above.
+   - If creating a new Task with Epic provided, add the parent relation
+   - Do NOT modify the parent Epic work item.
+
+4. **Create git branch**
+   ```bash
+   git stash
+   git checkout -b {taskId}-{taskNameSlug}
+   git stash pop
+   ```
+   - {taskId} is Jira task Id (lowercase), e.g., `az-122`
+   - {taskNameSlug} is kebab-case slug from task title, e.g., `progressive-search-system`
+   - Full branch name example: `az-122-progressive-search-system`
+
+5. Rename spec.md and corresponding building block:
+  - Rename to `_docs/iterative/feature_specs/{taskId}-{taskNameSlug}.md`
+  - Rename to `_docs/iterative/building_blocks/{taskId}-{taskNameSlug}.md`
+
+## Guardrails
+- No source code edits; only Jira task, file moves, and git branch.
+- If Jira creation/update fails, do not create branch or move files.
+- If AC/Tech fields are absent in Jira, append to Description.
+- **CRITICAL**: Extract the FULL Gherkin scenarios with all steps - do NOT create simple checklist items.
+- Do not edit parent Epic.
+- Always check for dev branch before proceeding.
+
@@ -0,0 +1,120 @@
+# Merge and Deploy Feature
+
+Complete the feature development cycle by creating PR, merging, and updating documentation.
+
+## Input parameters
+ - task_id (required): Jira task ID
+   Example: /gen_merge_and_deploy AZ-122
+
+## Prerequisites
+ - All tests pass locally
+ - Code review completed (or ready for review)
+ - Definition of Done checklist reviewed
+
+## Steps (Agent)
+
+### 1. Verify Branch Status
+```bash
+git status
+git log --oneline -5
+```
+ - Confirm on feature branch (e.g., az-122-feature-name)
+ - Confirm all changes committed
+ - If uncommitted changes exist, prompt user to commit first
+
+### 2. Run Pre-merge Checks
+
+**User action required**: Run your project's test and lint commands before proceeding.
+
+```bash
+# Check for merge conflicts
+git fetch origin dev
+git merge origin/dev --no-commit --no-ff || git merge --abort
+```
+
+ - [ ] All tests pass (run project-specific test command)
+ - [ ] No linting errors (run project-specific lint command)
+ - [ ] No merge conflicts (or resolve them)
+
+### 3. Update Documentation
+
+#### CHANGELOG.md
+Add entry under "Unreleased" section:
+```markdown
+### Added/Changed/Fixed
+- [TASK_ID] Brief description of change
+```
+
+#### Update Jira
+ - Add comment with summary of implementation
+ - Link any related PRs or documentation
+
+### 4. Create Pull Request
+
+#### PR Title Format
+`[TASK_ID] Brief description`
+
+#### PR Body (from template)
+```markdown
+## Description
+[Summary of changes]
+
+## Related Issue
+Jira ticket: [TASK_ID](link)
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactoring
+
+## Checklist
+- [ ] Code follows project conventions
+- [ ] Self-review completed
+- [ ] Tests added/updated
+- [ ] All tests pass
+- [ ] Documentation updated
+
+## Breaking Changes
+[None / List breaking changes]
+
+## Deployment Notes
+[None / Special deployment considerations]
+
+## Rollback Plan
+[Steps to rollback if issues arise]
+
+## Testing
+[How to test these changes]
+```
+
+### 5. Post-merge Actions
+
+After PR is approved and merged:
+
+```bash
+# Switch to dev branch
+git checkout dev
+git pull origin dev
+
+# Delete feature branch
+git branch -d {feature_branch}
+git push origin --delete {feature_branch}
+```
+
+### 6. Update Jira Status
+ - Move ticket to "Done"
+ - Add link to merged PR
+ - Log time spent (if tracked)
+
+## Guardrails
+ - Do NOT merge if tests fail
+ - Do NOT merge if there are unresolved review comments
+ - Do NOT delete branch before merge is confirmed
+ - Always update CHANGELOG before creating PR
+
+## Output
+ - PR created/URL provided
+ - CHANGELOG updated
+ - Jira ticket updated
+ - Feature branch cleaned up (post-merge)
+