# Project Documentation

## Code Quality (StableStack)

This project uses StableStack for code quality checks.

### Quick Reference

```bash
stablestack              # Run checks (auto-detects source dirs)
stablestack --fix        # Auto-fix issues where possible
stablestack --watch      # Re-run on file changes
stablestack explain DET001  # Explain a specific rule
stablestack --list-rules    # List all available rules
```

### Slash Commands

StableStack installs Claude Code slash commands:
- `/check` — Run StableStack checks and fix issues
- `/fix-production` — Monitor or fix CI/CD builds until production is green
- `/deterministic-ai` — Add `@cache` decorators to uncached LLM API calls

### Deterministic AI Caching

If `stablestack_cache.py` exists in the project root, wrap LLM API calls with `@cache`:
```python
from stablestack_cache import cache

@cache
def call_llm(prompt: str) -> str:
    return client.chat.completions.create(...)
```

Install with: `stablestack deterministic-ai`

### Key Rules to Follow

**Determinism (DET001-DET008):**
- Always sort dict/set iteration: `for k in sorted(d.keys())`
- Use tiebreakers when sorting: `sorted(items, key=lambda x: (x.priority, x.id))`
- Don't use `list(set(...))` for deduplication — it scrambles order

**Security (SEC001-SEC011):**
- Never hardcode secrets — use environment variables
- Use parameterized queries for SQL, never string concatenation
- Avoid `eval()` and `exec()`

**Quality (QUAL001-QUAL011):**
- Don't silently swallow exceptions with empty except blocks
- Name threads for easier debugging
- Use dataclasses instead of tuples with 3+ elements
