# Development Rules

## Conversational Style

- Keep answers short and concise
- No emojis in commits, issues, MR comments, or code
- No fluff or cheerful filler text
- Technical prose only, be kind but direct (e.g., "Thanks @user" not "Thanks so much @user!")
- Never use agreement theater.

## Conventions

All manual e2e walkthroughs use the local PostgreSQL instance. Credentials live in the repo-root `.env` (`PG_HOST`, `PG_PORT`, `PG_DATABASE`, `PG_USER`, `PG_PASSWORD`). Do not use DuckDB, SQLite, or in-memory fakes for e2e.

Source the env before running anything:

```bash
set -a && . ./.env && set +a
PGPASSWORD="$PG_PASSWORD" psql -h "$PG_HOST" -p "$PG_PORT" -U "$PG_USER" -d "$PG_DATABASE"
```

## Code Quality

- Do not preserve backward compatibility unless the user explicitly asks for it
- Prefer the cleanest, most SOLID, most expandable solution over the easiest migration.
- Always use Guard clauses if possible.
- Never use leading underscores in variables, functions, methods, or classes.
- No `any` types unless absolutely necessary
- Always add precise type hints.
  - Avoid bare `dict`, `list`, `tuple`, and `set`.
  - Prefer `dict[str, int | str]` over `dict`.
  - Prefer dataclasses or Pydantic models over dictionaries for structured data.
- Check the .venv for external API type definitions instead of guessing
- **NEVER use inline imports** — no imports inside functions, methods, or conditionals.
  - No `importlib.import_module(...)` for normal dependencies.
  - No `TYPE_CHECKING` imports unless a circular import is confirmed if you want to use it ask the user.
  - Always use top level imports
- Always ask before removing functionality or code that appears to be intentional
- Pydantic is allowed in `core/`; it is not infrastructure-only.

## Iron Law: Fix ALL Problems

- When you find a bug during testing, fix it. No exceptions.
- Never dismiss a problem as "pre-existing", "not related", or "out of scope".
- Never assume an external tool has the bug. The bug is in our code until proven otherwise with evidence.

## Dependency Management

- Always use `uv add` to add dependencies.
- Never manually edit dependency sections in `pyproject.toml` unless explicitly instructed.
- If dependency types are outdated, upgrade the dependency instead of weakening our code.

## Commands

After code changes, run the full quality gate and inspect complete output:

```bash
uv run ruff check
uv run ty check
uv run complexipy .
uv run tach check
```

Rules:

- Fix every error, warning, and info before claiming completion.
- Do not use truncated output or `tail` for verification.
- Use `uv run turbine` for manual CLI testing.
- Do not run broad or expensive commands unless the user asks.
- If you create or modify a test file, you MUST run that test file and iterate until it passes.
- NEVER commit unless user asks

## Changelog

Location: `CHANGELOG.md`

### Format

Use these sections under `## [Unreleased]`:

- `### Breaking Changes` - API changes requiring migration
- `### Added` - New features
- `### Changed` - Changes to existing functionality
- `### Fixed` - Bug fixes
- `### Removed` - Removed features

### Rules

- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist
- New entries ALWAYS go under `## [Unreleased]` section
- Append to existing subsections (e.g., `### Fixed`), do not create duplicates
- NEVER modify already-released version sections (e.g., `## [0.12.2]`)
- Each version section is immutable once released

## **CRITICAL** Git Rules for Parallel Agents **CRITICAL**

Multiple agents may work on different files in the same worktree simultaneously. You MUST follow these rules:

### Committing

- **ONLY commit files YOU changed in THIS session**

- ALWAYS include `fixes #<number>` or `closes #<number>` in the commit message when there is a related issue or MR
- NEVER use `git add -A` or `git add .` - these sweep up changes from other agents
- ALWAYS use `git add <specific-file-paths>` listing only files you modified
- Before committing, run `git status` and verify you are only staging YOUR files
- Track which files you created/modified/deleted during the session

### Forbidden Git Operations

These commands can destroy other agents' work:

- `git reset --hard` - destroys uncommitted changes
- `git checkout .` - destroys uncommitted changes
- `git clean -fd` - deletes untracked files
- `git stash` - stashes ALL changes including other agents' work
- `git add -A` / `git add .` - stages other agents' uncommitted work
- `git commit --no-verify` - bypasses required checks and is never allowed

### Safe Workflow

```bash
# 1. Check status first
git status

# 2. Add ONLY your specific files
git add src/turbine/core/analysis/my_file.py
git add CHANGELOG.md

# 3. Commit
git commit -m "fix(quality): description"

# 4. Push (pull --rebase if needed, but NEVER reset/checkout)
git pull --rebase && git push
```

### If Rebase Conflicts Occur

- Resolve conflicts in YOUR files only
- If conflict is in a file you didn't modify, abort and ask the user
- NEVER force push

### User override

If the user instructions conflict with rules set out here, ask for confirmation that they want to override the rules. Only then execute their instructions.
