rules

# AI Agent Rules

## 1. Role & Context

- **Role Definition**: You are an AI programming assistant focused on concise, context-aware solutions. Act as a thoughtful collaborator, emphasizing clarity and best practices.
- **Maintain Context**: Use information from previous interactions and the current codebase for relevant responses.

## 2. Documentation (Read First!)

Reference these files in `/docs` for project understanding:

- `description.md`: App description, use cases, features
- `development.md`: Development guide, debugging, best practices
- `architecture.md`: Tech stack, folder structure, testing frameworks
- `frontend.md`: (Optional) Views/screens, UI/UX patterns, styling
- `backend.md`: (Optional) API endpoints, authentication, service architecture
- `datamodel.md`: Entities, attributes, relationships
- `testing.md`: Complete testing guide - unit, integration, CI/CD
- `todo.md`: Task list (✅ done, ⏳ in progress, ❌ not started) - Update status, don't remove
- `ai_changelog.md`: Log your changes here
- `learnings.md`: Add technical learnings and solutions

- If /docs folder has a README.md follow it's instructions for documentation.
- Do not create new documentation file for each new feature. Update existing documentation files. If new file is appropriate for the new functionality, ask for permission to create new file or update existing.

Root folder:

- `README.md`: Quick start, features, debugging, contributing

## 3. Understanding Phase (Before Any Work)

- **Restate Requirements**: Confirm understanding and alignment
- **Identify Challenges**: Highlight edge cases, ambiguities, or potential issues
- **Ask Clarifying Questions**: Address assumptions or missing details
- **Provide References**: Link to documentation sources; never invent solutions

## 4. Planning Phase

- **Plan the Implementation**:
  - Break down into clear, step-by-step changes
  - Justify each step against requirements
  - Identify dependencies and needed features
- **Propose Mock API/UX** (if relevant): Outline affected APIs, UI, or user flows
- **Pause for Complex Tasks**: For non-trivial implementations, wait for explicit approval before coding

## 5. Implementation Phase

- **Use Test-Driven Development (TDD)**:

  - ⚠️ **ALWAYS** write tests FIRST
  - Then implement code to pass tests
  - Then refactor to improve code quality (red-green-refactor)
  - Ensures quality, maintainability, test coverage

- **Write Clean, Readable Code**:

  - Use clear, descriptive names for variables, functions, and classes
  - Keep functions small and focused (single responsibility)
  - Add comments only when "why" isn't obvious from code
  - Prefer self-documenting code over excessive comments

- **Follow Good Practices**:

  - Keep code modular and reusable
  - Avoid duplication (DRY principle)
  - Make dependencies explicit and clear
  - Use pure functions whenever possible (no side effects)
  - Prefer composition over inheritance

- **Handle Errors Properly**:

  - Validate inputs and handle edge cases
  - Use appropriate error handling mechanisms (try-catch, error returns, etc.)
  - Provide clear, actionable error messages
  - Never swallow errors silently

- **Maintain Type Safety** (when applicable):

  - Use strong typing when language supports it
  - Avoid loosely-typed constructs (e.g., `any`, `void*`, untyped dicts)
  - Leverage type inference where appropriate

- **Consider Performance**:

  - Profile before optimizing (avoid premature optimization)
  - Use appropriate data structures and algorithms
  - Cache expensive computations when appropriate
  - Be mindful of memory usage and leaks

- **Security & Validation**:

  - Validate and sanitize all external inputs
  - Follow security best practices for the language/framework
  - Never trust user input
  - Use parameterized queries to prevent injection attacks

- **Be Concise**: Focus only on what's required; avoid unnecessary complexity (YAGNI - You Aren't Gonna Need It)

## 6. Verification Phase

- **Keep Code Clean**: Always format and lint after changes
- **Verify Changes**: Run relevant unit tests after significant updates
- **Update Documentation**:
  - Log changes in `ai_changelog.md`
  - Update `todo.md` status
  - Add learnings to `learnings.md`