Hankanman

Fix TypeScript type inference loss when dynamically constructing Zod object schemas. Use when: (1) `z.infer<typeof schema>` produces `Record<string, unknown>` instead of typed fields, (2) Building a schema factory that constructs `z.object()` from dynamic field maps, (3) Component props typed from Zod schema show 'unknown' for all fields, (4) Type error "'data.fieldName' is of type 'unknown'" after refactoring schemas to use a factory pattern. Covers Zod 3 and Zod 4.

Access the Home Assistant REST API using environment variables HA_URL and HA_TOKEN exported in ~/.zshrc. Use when: (1) need to query Home Assistant entity states, (2) need to call HA services programmatically, (3) need to debug or inspect HA integration state, (4) user asks to interact with their Home Assistant instance. Covers authentication, common endpoints, and usage patterns.

Fix Better Auth performance anti-pattern: manual db.$setAuth() vs. reusing cached client. Use when: (1) Server actions or components create new auth contexts with db.$setAuth(), (2) Functions accept User parameter just to create auth context, (3) Dashboard or data-heavy pages are slow (>500ms), (4) Multiple sequential auth operations in same request. Applies to Better Auth v1.4.10+ with JWE cookie cache and ZenStack ORM.

Fix for "An error occurred in the Server Components render" in Next.js production builds when using ZenStack ORM with Better Auth. Use when: (1) Generic Server Components error in production with no stack trace, (2) Works in dev but fails in production, (3) Using manual db.$setAuth() instead of authenticated client from auth()/requireRole(). Symptoms include Sentry errors with digest but no details, or blank error pages. Solution: Always use the pre-configured db client from auth() or requireRole() result instead of manually creating auth context with db.$setAuth({ id, role }).

Fix timezone drift when using JavaScript Date methods with UTC-stored times. Use when: (1) Times shift by user's timezone offset (e.g., 09:00 UTC becomes 10:00 in BST browsers), (2) Database stores times in UTC but display shows wrong hours, (3) Inconsistent time behavior across users in different timezones, (4) Using getHours/getMinutes/setHours with Date objects that should stay in UTC. Replace local time getters/setters with UTC variants to prevent automatic timezone conversion.

Refactor Next.js + Better Auth authentication to minimal API with discriminated unions. Use when: (1) Too many auth helper functions causing maintenance burden, (2) Want perfect type safety without optional chaining, (3) Need to optimize auth performance with aggressive cookie caching, (4) Using Better Auth v1.4+ with Next.js 16 App Router and ZenStack ORM. Covers progressive refactoring from backward-compatible to breaking changes, discriminated union type patterns, and systematic multi-file migration.

Fix TypeScript errors when integrating react-big-calendar drag-and-drop addon in Next.js/React projects. Use when: (1) Getting "Module has no exported member 'EventInteractionArgs'" error, (2) EventWrapperProps type missing 'children' property causing type errors, (3) stringOrDate type mismatches in onEventDrop/onEventResize handlers. Covers proper type imports and generic type parameters for withDragAndDrop HOC.

Integrate react-big-calendar with Next.js 16 App Router and shadcn/ui. Use when: (1) Need to add a visual calendar to Next.js app, (2) Want calendar that works with server/client component split, (3) Need to integrate with shadcn/ui theming, (4) Building scheduling or availability features. Covers component structure, CSS imports in client components, date-fns localizer setup, and event styling with shadcn variables.

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.

Automate GitHub Projects v2 planning from codebase analysis. Use when: (1) Need to create comprehensive project board with epics and user stories, (2) Converting codebase analysis into GitHub issues, (3) Bulk issue creation with labels and status synchronization, (4) Setting up kanban board with proper organization. Handles GitHub CLI authentication, GraphQL API for status updates, rate limiting, and project-issue linking.