# Critical Rules for AI Assistants

> **NON-NEGOTIABLE**: These rules MUST be followed without exception.
> Violating these standards is a critical error.

---

## 1. NEVER Push Directly to Main Branch

**ALWAYS use pull requests. NEVER push to main/master.**

### Prohibited Commands

```bash
# ❌ NEVER do this
git push origin main
git commit && git push  # when on main branch
```

### Required Workflow

```bash
# ✅ ALWAYS do this
git checkout -b feature/my-change
# Make changes
git add .
git commit -m "feat: description

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: stavxyz <hi@stav.xyz>"
git push -u origin feature/my-change
gh pr create
```

### AI Assistant Requirements

**Before pushing any code:**
- [ ] Check current branch: `git branch --show-current`
- [ ] If on main/master: STOP and create feature branch first
- [ ] Never use `git push` when on main branch
- [ ] Always create PR, never merge directly
- [ ] Include proper commit message with co-authors

**Recovery if accidentally on main:**
```bash
# If you realize you're on main
git checkout -b feature/fix-name
# Continue work on feature branch
```

---

## 2. NEVER Modify System Python

**ALWAYS use virtual environments. NEVER install packages globally.**

### Prohibited Commands

```bash
# ❌ NEVER run these - they corrupt user's system
pip install <package>
python3 -m pip install --user <package>
sudo pip install <package>
pip3 install <package>
```

### Required Workflow

```bash
# ✅ ALWAYS do this
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

# Now safe to install
pip install -r requirements.txt
```

### AI Assistant Requirements

**Before running `pip install`:**
- [ ] Check if venv active: `which python`
- [ ] Verify output shows `.venv/bin/python`
- [ ] If not active: Create and activate venv first
- [ ] NEVER use `--user` flag
- [ ] NEVER use `sudo pip`
- [ ] NEVER install without active venv

**If no venv exists:**
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

---

## 3. File Operations

**Read before write. Verify paths exist.**

### Requirements

- [ ] Use Read tool before Edit/Write on existing files
- [ ] Verify file paths with Glob before operations
- [ ] Check directory exists before creating files
- [ ] Preserve exact indentation when editing

### Pattern

```bash
# 1. Read first
Read file_path

# 2. Then edit
Edit file_path old_string new_string

# Or write for new files (but prefer Edit for existing)
Write file_path content
```

---

## 4. Testing

**Run tests before committing. Verify changes don't break existing functionality.**

### Requirements

- [ ] Run `pytest tests/ -v` before every commit
- [ ] Fix failing tests immediately
- [ ] Don't commit if tests fail (unless explicitly acceptable)
- [ ] Check coverage for new code

### Commands

```bash
# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src

# Run specific test file
pytest tests/unit/test_file.py -v

# Skip slow tests
pytest -m "not e2e"
```

---

## 5. Code Quality

**Run linting and formatting before committing.**

### Requirements

- [ ] Run `ruff check --fix` before commit
- [ ] Run `ruff format` before commit
- [ ] Run `mypy src/` for type checking
- [ ] Fix all errors before pushing

### Commands

```bash
# Lint and auto-fix
ruff check --fix src/ tests/

# Format code
ruff format src/ tests/

# Type check
mypy src/

# All in sequence
ruff check --fix . && ruff format . && mypy src/ && pytest tests/
```

---

## 6. Structured Logging

**Use logging, never print().**

### Prohibited

```python
# ❌ NEVER use print() for logging
print(f"Processing {item_id}")
print("Error:", error)
```

### Required

```python
# ✅ ALWAYS use structured logging
import structlog

logger = structlog.get_logger()

logger.info("item_processing_started", item_id=item_id)
logger.error("processing_failed", item_id=item_id, error=str(error))
```

---

## 7. Type Hints

**All functions require type hints.**

### Requirements

- [ ] Function parameters have types
- [ ] Return types specified
- [ ] Use `typing` module for complex types
- [ ] Data classes use type annotations

### Pattern

```python
from typing import Optional
from pathlib import Path

def process_file(
    path: Path,
    threshold: float = 0.8
) -> tuple[pd.DataFrame, list[str]]:
    """Process file and return (result, errors)."""
    ...
```

---

## 8. Error Handling

**Only catch expected exceptions. Let unexpected errors bubble up.**

### Requirements

- [ ] Only catch specific exception types
- [ ] Never use bare `except:` or `except Exception:`
- [ ] Provide clear error messages
- [ ] Re-raise with context using `from e`

### Pattern

```python
# ✅ GOOD
try:
    df = pd.read_excel(path)
except BadZipFile as e:
    raise ValueError(f"Corrupt Excel file: {path}") from e

# ❌ BAD
try:
    df = pd.read_excel(path)
except Exception:  # Too broad
    return None
```

---

## 9. File Size Limit

**No file should exceed 500 lines.**

### Requirements

- [ ] Check line count of modified files
- [ ] If >500 lines: Extract functions, split into submodules
- [ ] Move constants to separate config file
- [ ] Create subpackage if module grows too large

### Recovery

```bash
# Check file size
wc -l src/myproject/large_file.py

# If >500 lines, split it
# Create src/myproject/module/
# Move functions to separate files
```

---

## 10. Dependency Injection

**Don't create dependencies inside classes. Inject them.**

### Requirements

- [ ] Classes accept dependencies as constructor parameters
- [ ] Makes testing easy (inject mocks)
- [ ] No hard-coded dependency instantiation

### Pattern

```python
# ✅ GOOD
class ProcessingService:
    def __init__(
        self,
        parser: DataParser,
        validator: DataValidator
    ):
        self.parser = parser
        self.validator = validator

# Usage with real dependencies
service = ProcessingService(
    parser=ExcelParser(),
    validator=SchemaValidator()
)

# Testing with mocks
service = ProcessingService(
    parser=Mock(spec=DataParser),
    validator=Mock(spec=DataValidator)
)
```

---

## Pre-Operation Checklist

**Run this checklist before ANY operation:**

1. [ ] Read project-specific `.claude/CLAUDE.md` (if exists)
2. [ ] Check virtual environment active: `which python`
3. [ ] Check current git branch: `git branch --show-current`
4. [ ] Verify not on main/master branch
5. [ ] Read relevant files before editing
6. [ ] Run tests after changes
7. [ ] Create PR, never push to main

---

## Common Mistakes

**These are the most frequent critical errors:**

1. ❌ Running `pip install` without checking venv is active
2. ❌ Pushing to main branch instead of creating PR
3. ❌ Using `print()` instead of structured logging
4. ❌ Catching generic `Exception` instead of specific types
5. ❌ Writing files over 500 lines
6. ❌ Functions without type hints
7. ❌ Committing without running tests
8. ❌ Using bare `except:` clauses

---

## Emergency Recovery

**If you realize you've violated a critical rule:**

### Pushed to main accidentally

```bash
# 1. Immediately revert
git revert HEAD --no-edit
git push origin main

# 2. Create feature branch from the commit
git checkout -b feature/fix-accidental-push <commit-hash>
git push -u origin feature/fix-accidental-push

# 3. Create PR
gh pr create
```

### Installed packages without venv

```bash
# Can't undo, but prevent future mistakes:
# 1. Create venv now
python3 -m venv .venv
source .venv/bin/activate

# 2. Reinstall in venv
pip install -r requirements.txt

# 3. Inform user to check system Python
# (User may need to clean up system packages)
```

---

## Questions to Ask Yourself

**Before executing any command, ask:**

1. Am I in a virtual environment? (`which python`)
2. Am I on a feature branch? (`git branch --show-current`)
3. Have I read the file I'm about to edit? (Use Read tool)
4. Will this change break tests? (Run `pytest` before commit)
5. Is this file growing too large? (Check `wc -l`)
6. Am I using type hints? (Check function signatures)
7. Am I catching specific exceptions? (Not generic `Exception`)

---

## Related Documentation

- **Engineering Standards**: `.claude/docs/ENGINEERING_STANDARDS.md`
- **Knowledge Base**: `.claude/knowledge/` (tactical tips)
- **Full Standards**: `/docs/ENGINEERING_STANDARDS.md` (human-facing)

---

**Status**: These rules are NON-NEGOTIABLE. Updated: 2025-12-04
