# Code Quality Standards

Standards for code quality, commit triggers, and pre-completion verification.

## Commit Triggers

Create a commit after ANY of these:
- Completing a single feature or function
- Fixing a bug (even small ones)
- Adding or modifying tests
- Updating documentation
- Before switching to a different task
- Every 15-30 minutes of active coding (at natural breakpoints)

## Immutability Principle

**Always create new objects, never mutate existing ones:**

```
WRONG:  modify(original, field, value)  -- changes original in-place
RIGHT:  update(original, field, value)  -- returns new copy with change
```

Immutable data prevents hidden side effects, simplifies debugging, and enables safe concurrency. Apply in all languages -- use spread operators, `copy()`, `with` methods, or equivalent.

## Pre-Completion Quality Checklist

Before marking any task complete, verify:
- [ ] Code is readable with well-named variables and functions
- [ ] Functions are small (<50 lines)
- [ ] Files are focused (<800 lines)
- [ ] No deep nesting (>4 levels)
- [ ] Proper error handling at every level
- [ ] No hardcoded values (use constants or config)
- [ ] Immutable patterns used (no mutation)

## Communication Style

- Be concise but informative
- Explain "why" not just "what" when making decisions
- Proactively surface potential issues or alternatives
- Ask clarifying questions when requirements are ambiguous

## Task Management

Use task tracking tools for multi-step work (3+ steps):
- Create tasks before starting complex work (plan first)
- Mark tasks as in-progress when starting, completed when fully done
- Never mark completed if tests fail or implementation is partial
- Express dependencies between tasks
- Keep task subjects in imperative form ("Build chat bridge", not "Chat bridge")
- Work tasks in order of dependencies

## Documentation Lookup (Token-Conscious)

Use a tiered approach to minimize token usage:

1. **Existing knowledge** (preferred): Common patterns, stable APIs you know well
2. **Lightweight fetch**: Simple lookups to official documentation
3. **LLM-optimized docs**: Check `/llms.txt` endpoints when available
4. **Heavy documentation tools**: Reserve for complex queries or unfamiliar libraries

Each heavy documentation query can inject 5-20k tokens. Multiple queries compound quickly.