🤖 AI Contributor Guide

# 🤖 AI Contributor Guide

Welcome, autonomous agent!  This document explains the project layout, coding conventions, and the extra steps you—an AI system—should follow when proposing changes to **BG Analyzer**.

> **If your modification changes user‑visible behaviour or usage instructions, you must also update** `README.md`, sample configuration files, and any other helper docs needed to keep everything in sync.

---

## 1 · Repository Map

| Path                     | What you’ll find                                                                     | Typical agent tasks                                          |
| ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `/bg_analyzer/ingest/`   | Parsers that convert device exports (CGM, pump, pen, food logs) into a common schema | Add a new `*.py` parser, expand the schema, write unit tests |
| `/bg_analyzer/analysis/` | Core algorithms for event filtering and ICR/ICF estimation                           | Optimise maths, add new metrics or context‑aware models      |
| `/bg_analyzer/report/`   | Renderers that turn analysis results into Markdown & JSON                            | Create new output formats, tweak visualisation               |
| `/cli.py`                | Click‑based command‑line interface entry point                                       | Extend CLI flags, improve UX messages                        |
| `/samples/`              | Example CSV files for manual and CI tests                                            | Add fresh samples when supporting new devices                |
| `/tests/`                | Pytest suite & fixtures                                                              | Write tests for every new behaviour                          |
| `/docs/`                 | Longer‑form design/architecture docs (optional)                                      | Add detailed specs, diagrams                                 |

---

## 2 · Workflow for Agents

1. **Sync and plan**
   *Read open issues or create one describing the change.*  Reference it in your PR.
   If anything is unclear, add a bullet to `QUESTIONS.md` so the product owner can respond.
2. **Create a feature branch**
   `feature/<short‑slug>` or `fix/<short‑slug>`.
3. **Write the code**

   * Follow existing folder conventions.
   * Add/modify docstrings in *Google‑style* format.
   * Maintain type hints (`mypy` passes).
   * Keep functions <50 LOC where feasible.
4. **Update documentation**

   * If UX or CLI changes, update `README.md`.
   * If developer‑facing behaviour changes, update `agents.md` or create a doc under `/docs/`.
   * Refresh examples in `/samples/` if data format changes.
   * When a question in `QUESTIONS.md` is answered, reflect it in the docs and remove that bullet.
5. **Validate**

   * Run `pre‑commit run --all-files` (black, isort, flake8, mypy, etc.).
   * Run `pytest ‑q`—tests must pass and coverage ≥ 90 %.
   * Execute `python cli.py --help` to ensure CLI still works.
6. **Commit**
   Use *Conventional Commits*:
   `feat(ingest): add Abbott Libre CSV parser`
   `fix(analysis): handle zero‑carb corrections`
7. **Pull Request**

   * Title = concise, imperative.
   * Body = *What + Why + How*, link the issue.
   * Checklist ticked (tests, docs, coverage).
   * Update `ROADMAP.md` task status in the same PR (move card or tick box).
   * Tag `@maintainers` for review.

---

## 3 · Design Principles

* **Local‑first privacy**: never send raw health data to external APIs unless an integration is explicitly enabled.
* **Predictability over complexity**: favour transparent calculations before opaque ML.  Include comments & references if statistical methods are added.
* **User empathy**: error messages must be actionable and non‑alarmist; analytics should default to safe, conservative suggestions.

---

## 4 · Updating Helper Files

When your change alters:

| Change type             | Docs to update                                                                    |
| ----------------------- | --------------------------------------------------------------------------------- |
| CLI flag, config option | `README.md` (Quick Start & Expected CSV columns)                                  |
| Device/data source      | `README.md` (Capabilities) + `/samples/`                                          |
| Repo structure          | `agents.md` + `/docs/architecture.md`                                             |
| Algorithms/metrics      | `README.md` (Current capabilities) + Possibly a new doc under `/docs/algorithms/` |

Failing to update docs will trigger **CI Doc‑Check** and block merge.

---

## 5 · Test & Documentation Utilities

* **Generate latest user report**: `make demo-report` → writes to `reports/`.
* **Open coverage HTML**: `make cov`.
* **Lint markdown**: `mdformat -i *.md`  (runs in pre‑commit).

---

## 6 · Semantic Versioning & Changelog

The project follows **SemVer**.  The `CHANGELOG.md` is auto‑generated from Conventional Commits during release (`npm version`‑style script).  When you merge to `main`, CI may tag a version bump.  *Breaking changes require a `!` in the commit scope.*

---

Happy coding, fellow agent – keep the loops tight, the tests green, and the docs fresh! 🚀