Area-Occupancy-Detection

Use when scoping new research, a thesis/blog post, a grant-style pitch, or a "what should we work on next" planning session for Area Occupancy Detection — maps open, unproven "beyond state-of-the-art" problems (reliability vs raw sensors, per-home transition learning, predictive pre-heat/pre-light, Home-Assistant-core-grade quality) to concrete first steps in this repo. Do not use for day-to-day bugfixing, the active prior/likelihood accuracy campaign, or exact formula lookup — see "When NOT to use this" below.

Use when you need to MEASURE what Area Occupancy Detection is actually doing instead of guessing — downloading and reading the HA diagnostics export, interpreting a health/repair issue, reading hourly-analysis debug logs, or using the simulator to compare a predicted probability against the live sensor. Load this before answering "why is this area stuck occupied", "is the prior learned correctly", "what does this repair mean", or "how do I reproduce this probability by hand".

Use when turning a hunch, user report, or measurement into an accepted change to AOD's Bayesian/learning math — deciding whether a root-cause theory is proven, designing the discriminating experiment (DB query, simulator run, or predicted-numbers test), shipping an experimental capability behind a config flag, or adversarially refuting a claimed bug/fix. Also load this before trusting any "verified" claim from a single home's data or a single refutation pass. NOT for routine bugfixes with an obvious, already-known mechanism (use aod-debugging-playbook) or for the state of specific frontier research questions (use aod-research-frontier).

Use when you need to understand WHY Area Occupancy Detection is built the way it is before changing coordinator.py, area/area.py, utils.py, data/analysis.py, data/decay.py, data/entity.py, or anything under db/ — the single-coordinator-many-areas design, the exact probability pipeline order, the three timers, DB session/executor rules, or the list of invariants a change must not violate. Load this before any PR that touches Bayesian math, timers, DB schema, or entity evidence, and whenever asked "why does this work this way" or "is it safe to change X".

Use when setting up, resetting, or debugging the local development environment for Area Occupancy Detection — bootstrap fails, `uv sync` errors, wrong Python version, ruff or pytest behaving differently locally vs CI, uv.lock showing unexpected diffs, devcontainer questions, or anything mentioning scripts/bootstrap, scripts/setup, scripts/lint, scripts/test, libturbojpeg, or "three uv projects".

Use before opening, reviewing, or merging any PR against Area Occupancy Detection (AOD) — especially anything touching Bayesian math (utils.py sigmoid pipeline), priors, decay/half-life, likelihoods, config schema (const.py CONF_*/DEFAULT_*), the config-entry migration ladder (migrations.py), or the DB schema (db/schema.py). Also load when deciding how to reply to CodeRabbit, when bumping the release version, when someone proposes a new per-sensor config knob, or when you're unsure whether a change needs a version bump, a migration, or extra validation before merge.

Use when adding, renaming, removing, or debugging any CONF_* / DEFAULT_* configuration key, config_flow.py schema, strings.json/translations entry, migrations.py version bump, or sensor default in Area Occupancy Detection; when a user reports a setting "not sticking", reverting, or silently overwritten (e.g. decay half-life, threshold, sensor precision); or when deciding whether a change needs a CONF_VERSION bump. Covers the full CONF_* catalog with defaults/ranges/stability, the decay half-life 0-sentinel, the

Use when triaging a live Area Occupancy Detection symptom report — occupancy stuck on/won't clear, occupancy won't turn on, probability pinned at 0.99 or 0.01, wrong or spammy repair issues, a config setting that seems to be "ignored" (especially decay half-life or min_prior_override), the database growing/slow, config-flow errors, or entities showing 100% occupied right after a restart. Also load this before touching timezone/DST datetime handling, decay half-life resolution, or prior/global_prior calculation code — these are the project's three most expensive historical bug classes and this skill has the exact traps.

Use when writing or editing anything under docs/docs/ (mkdocs site), README.md, CONTRIBUTING.md, CHANGELOG.md, docstrings, commit messages, PR titles, or GitHub Release notes for Area Occupancy Detection — or when a code change needs an accompanying doc update and you're deciding what/where to write. Trigger words: "update the docs", "add a features page", "write a docstring", "release notes", "mkdocs nav", "stale doc", "CHANGELOG".

Use when writing or reviewing anything that positions Area Occupancy Detection (AOD) against the rest of the Home Assistant ecosystem — README claims, release notes, "how is this different from X" answers, comparisons to HA core's bayesian platform or Bermuda/ESPresense, or any statement that a feature is "novel", "state of the art", or "proven". Also load before approving a PR description or doc page that cites accuracy/precision numbers, or before answering "is adjacency validated on real homes yet".

Use before touching decay half-life, prior/global-prior calculation, sensor-health repairs, sleep-presence detection, recorder/DB write volume, adjacent-areas, timezone/DST-sensitive datetime code, or the config-flow advanced-options gating — to check whether the bug you're about to fix (or the fix you're about to write) already happened before. Load this when a symptom rhymes with "custom value silently reverted to a default", "repairs fire spuriously / return after Ignore", "prior pinned near 0.99 or 0.01", "TypeError offset-naive and offset-aware", or "recorder database growing too fast".

Executable, decision-gated campaign for making learned priors and likelihoods (global prior, 168 time-priors, per-sensor P(E|H) from correlation analysis, decay half-life resolution) trustworthy on real homes. Load this when a user reports "prior stuck at 0.99/0.01", "occupancy probability doesn't match reality", "false transitions", "decay clears too fast/slow", "correlation/likelihood looks wrong", or when asked to touch data/prior.py, data/analysis.py's PriorAnalyzer, db/correlation.py, or data/decay.py half-life resolution. This is the flagship operation order for the project's hardest live problem — treat it as a runbook, not background reading.

Use when you are about to touch, review, or debug any probability/statistics math in Area Occupancy Detection (priors, likelihoods, decay half-lives, logit-space boosts, correlation confidence, timezone/interval bucketing) and need to hand-verify the numbers BEFORE trusting a PR, a bug report, or your own patch. Trigger on tasks like "does this prior look right", "is this decay curve correct", "why did the prior pin at 0.99", "check this ratio/denominator", "audit this new coupling between areas for feedback loops", or any request to prove a calculation from first principles rather than just running the test suite.

Use when you need to actually run the integration or its satellite tools — launch the devcontainer's Home Assistant instance, add an area through the config-flow UI, enable debug logging, find the SQLite DB, read or interpret the hourly analysis pipeline's log lines, run the Flask simulator locally, or understand the release/HACS/docs-deploy machinery. Triggers on "how do I run this", "start HA", "add an area", "where's the database", "Step N FAILED", "sync_states", "run the simulator", "cut a release", "HACS", or "docs site".

Use when writing, reviewing, or deciding what evidence is required for ANY change to Area Occupancy Detection — before opening a PR, when asked "is this tested enough?", when adding a test for math/behavior/config/DB code, when coverage or CI is failing, or when a reviewer/CodeRabbit flags a test as rigged, redundant, or encoding a bug. Covers the evidence bar per change class, conftest.py fixture anatomy, the golden test-file map, and lint/coverage gates.

Load when you need the actual math behind Area Occupancy Detection's probability engine — logit-space evidence combination, prior composition (global/time/purpose-floor), exponential decay half-lives, the sleep awake/asleep half-life switch, wasp-in-box state logic, adjacent-areas Bayesian boost/decay-modifier, or the transition-lookup smoothing fallback. Use before touching utils.py, data/prior.py, data/decay.py, data/purpose.py, data/adjacency.py, data/trajectory.py, db/transitions.py, or db/correlation.py, or before answering "why does this area's probability say X" / "why is decay too fast/slow" / "why is the prior pinned near 0.99" questions.