sgr-deep-research / rules

---
description: Workflow rules for bug fixes, new features, and testing
globs: **/*.py, tests/**/*.py
alwaysApply: true
---

# Workflow Rules for Bug Fixes and New Features

## Mandatory Flow (Use Always)

For **new features** follow this order strictly. Do not skip steps.

1. **Plan** - write what to do for the new feature
2. **Tests (red)** - write tests for the feature, run them, ensure they fail
3. **Code** - implement the feature
4. **Tests (green)** - run the new tests, ensure they pass
5. **All tests** - run full test suite, ensure everything passes
6. **Documentation** - write docs and examples if needed
7. **Linter** - run linter, fix all issues
8. **Report** - write what was done

## Virtual Environment

**IMPORTANT**: Virtual environment is located in `.venv` directory. Always activate it before running tests or commands:

**Linux/macOS:**
```bash
source .venv/bin/activate
```

**Windows (PowerShell):**
```powershell
.venv\Scripts\Activate.ps1
```

**Windows (CMD):**
```cmd
.venv\Scripts\activate.bat
```

**Windows (Git Bash/WSL):**
```bash
source .venv/Scripts/activate
```

## New Features (TDD Approach)

### Mandatory Workflow for New Features

**CRITICALLY IMPORTANT**: When user asks to implement a new feature (using words "фича", "feature", "новая функция", "добавить", "implement", "add"), **always** use the flow from "Mandatory Flow" above.

**Do not skip any step!** Order: plan → tests (red) → code → tests (green) → all tests → documentation → linter → report.

### Step-by-step Process for New Features

1. **Plan**
   - Write what to do for the new feature (scope, steps, files to touch)
   - Clarify expected behavior and edge cases
   - Fix the order of work before writing code or tests

2. **Write tests and verify they fail (red)**
   - Create tests in corresponding file `tests/test_*.py`
   - Tests must **fail** (red) because feature does not exist yet
   - Tests must clearly describe expected behavior
   - Run tests and ensure they fail for the right reason:
     - **Linux/macOS**: `source .venv/bin/activate && pytest tests/test_*.py::test_name -v`
     - **Windows**: `.venv\Scripts\activate && pytest tests/test_*.py::test_name -v`
   - If tests pass unexpectedly, review test logic

3. **Implement feature (code)**
   - Write code that implements the new feature
   - Follow rules from @code-style.mdc and @architecture.mdc
   - Use @implementation-order.mdc if adding new classes
   - Implement one class/module at a time

4. **Run new tests and verify they pass (green)**
   - Run the new tests:
     - **Linux/macOS**: `source .venv/bin/activate && pytest tests/test_*.py::test_name -v`
     - **Windows**: `.venv\Scripts\activate && pytest tests/test_*.py::test_name -v`
   - Tests must **pass** (green)
   - Ensure feature behaves as expected

5. **Run all tests**
   - Execute full test suite:
     - **Linux/macOS**: `source .venv/bin/activate && pytest tests/ -v`
     - **Windows**: `.venv\Scripts\activate && pytest tests/ -v`
   - **All tests must be green**
   - If any fail, fix them before proceeding

6. **Documentation and examples (optional)**
   - Update or add documentation for the new feature if necessary
   - Add examples if needed
   - Update API docs if needed
   - Keep docs clear and complete

7. **Run linter**
   - Execute linter:
     - **Linux/macOS**: `source .venv/bin/activate && pre-commit run -a`
     - **Windows**: `.venv\Scripts\activate && pre-commit run -a`
   - Fix all lint issues; repeat until linter passes

8. **Report**
   - Short summary of what was done
   - What was implemented, which tests added/changed
   - Test and linter results
   - Documentation changes

### Report Structure Example for New Features

```markdown
## Feature: [brief description]

### Implementation
1. Plan: [what was planned - scope, steps]
2. Added tests in `tests/test_module.py` (initially red), verified they fail
3. Implemented `new_method` in `sgr_agent_core/module.py`
4. Ran new tests - passed (green)
5. Ran all tests - all green (239 passed)
6. Updated documentation in `docs/*/framework/feature.md`, added example if needed
7. Ran linter - all checks passed
8. Report: what was done (this block)

### Changed Files
- `sgr_agent_core/module.py` - added new_method implementation
- `tests/test_module.py` - added tests for new feature
- `docs/*/framework/feature.md` - added documentation for new feature
```

## Bug Fixes (TDD Approach)

### Mandatory Workflow for Bug Fixes

**CRITICALLY IMPORTANT**: When fixing a bug, use the same flow as for features. Order: plan → tests (red) → code → tests (green) → all tests → documentation → linter → report.

**Do not skip any step!**

### Step-by-step Process for Bug Fixes

1. **Plan**
   - Define what is broken and where to fix it (scope, cause, files to change)

2. **Write test reproducing bug and verify it fails (red)**
   - Create test in `tests/test_*.py` that reproduces the bug
   - Test must **fail** (red)
   - Run test and ensure it fails for the right reason:
     - **Linux/macOS**: `source .venv/bin/activate && pytest tests/test_*.py::test_name -v`
     - **Windows**: `.venv\Scripts\activate && pytest tests/test_*.py::test_name -v`

3. **Fix code**
   - Implement the fix
   - Follow @code-style.mdc and @architecture.mdc
   - Change only what is needed to fix the bug

4. **Run new test and verify it passes (green)**
   - Run the new test - it must **pass** (green)
   - Confirm the bug is fixed

5. **Run all tests**
   - Run full suite: `pytest tests/ -v`
   - **All tests must be green**

6. **Documentation**
   - Update docs to reflect the fix, add examples if needed

7. **Run linter**
   - `pre-commit run -a`, fix all issues until clean

8. **Report**
   - What was fixed, which tests added/changed, test and linter results

### Report Structure Example for Bug Fixes

```markdown
## Bug Fix: [brief description]

### Problem
[Bug description]

### Solution
1. Plan: [what was broken, where to fix]
2. Added test in `tests/test_module.py` (red), verified it fails
3. Fixed `method_name` in `sgr_agent_core/module.py`
4. Ran new test - passed (green)
5. Ran all tests - all green
6. Updated documentation in `docs/en/framework/module.md`
7. Ran linter - all checks passed
8. Report: what was done (this block)

### Changed Files
- `sgr_agent_core/module.py` - fixed processing logic
- `tests/test_module.py` - added test for bug
- `docs/en/framework/module.md` - updated documentation
```

## Final Verification Before Reporting

**MANDATORY**: Before writing the final report for any work (bug fix or new feature), complete the full flow. The last steps must be in this order:

1. **All tests pass** - `pytest tests/ -v`, no failures
2. **Documentation updated** - docs and examples (if needed) are done
3. **Linter passes** - `pre-commit run -a`, all checks green
4. **Then write report** - include what was done, test results, linter results

## Testing Commands Reference

### Linux/macOS
```bash
# Activate virtual environment
source .venv/bin/activate

# Run all tests
pytest tests/ -v

# Run specific test
pytest tests/test_module.py::TestClass::test_method -v

# Run with coverage
pytest tests/ --cov=sgr_agent_core --cov-report=term-missing

# Run linter
pre-commit run -a

# Run both tests and linter
pytest tests/ -v && pre-commit run -a
```

### Windows (PowerShell/CMD)
```powershell
# Activate virtual environment (PowerShell)
.venv\Scripts\Activate.ps1

# Activate virtual environment (CMD)
.venv\Scripts\activate.bat

# Run all tests
pytest tests/ -v

# Run specific test
pytest tests/test_module.py::TestClass::test_method -v

# Run with coverage
pytest tests/ --cov=sgr_agent_core --cov-report=term-missing

# Run linter
pre-commit run -a

# Run both tests and linter (PowerShell)
pytest tests/ -v; if ($?) { pre-commit run -a }

# Run both tests and linter (CMD)
pytest tests/ -v && pre-commit run -a
```

### Windows (Git Bash/WSL)
```bash
# Activate virtual environment
source .venv/Scripts/activate

# Run all tests
pytest tests/ -v

# Run specific test
pytest tests/test_module.py::TestClass::test_method -v

# Run with coverage
pytest tests/ --cov=sgr_agent_core --cov-report=term-missing

# Run linter
pre-commit run -a

# Run both tests and linter
pytest tests/ -v && pre-commit run -a
```

## References

@testing.mdc
@code-style.mdc
@architecture.mdc

More agent context in vamplabAI/sgr-deep-research

6 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• vamplabAI/sgr-agent-core1.1k