# Development Process — Test-Develop-Debug

## Workflow
1. Write or update tests for the target behavior
2. Implement the minimal code to pass
3. Debug failures, fix, re-run
4. Commit and push after each phase completes
5. GitHub Actions builds container images and pushes to GHCR
6. Deploy to cluster via `kubectl apply`

## Testing
- Use `pytest` with `pytest-asyncio` for async code
- Tests live alongside service code or in a top-level `tests/` directory
- Run tests with `pytest --tb=short -q` or `pytest -x` for fail-fast
- Focus on core logic, not mocking infrastructure

## Build and Deploy
- Always build and test Docker images locally before pushing to GitHub
- Only push to GitHub after local build succeeds — don't waste CI credits on broken builds
- Dockerfile at `docker/Dockerfile`
- GitHub workflow at `.github/workflows/build.yml`
- Images tagged as `ghcr.io/celesrenata/stonks-oracle/<service>:<sha>` and `:latest`
- K8s manifests reference GHCR images
- Deploy: `kubectl apply -f infra/k8s/`
- Local build: `make build` → verify → `git push` → CI builds and pushes to GHCR

## Git Conventions
- Commit after each completed phase task
- Commit message format: `phase N: short description`
- Push to `main` branch triggers CI

## Code Style
- Python 3.12, type hints everywhere
- Pydantic for data validation
- FastAPI for HTTP services
- asyncio + asyncpg/aioredis for async I/O
- Minimal dependencies, prefer stdlib where possible

## Documentation
- Do NOT create large summary/success markdown files after each step
- Keep notes short, concise, and organized under `docs/notes/`
- Name note files to match the task they relate to (e.g. `docs/notes/phase0-k8s-manifests.md`)
- This makes them recallable by task without guessing
- If a note isn't useful for future reference, don't write it