open-garden-planner

Reference pack for Open Garden Planner's SHIPPED 3D + sun/shade subsystems (Phase 14, v1.24.5 – v1.24.12 — complete; epic #255 closed). Load this skill when MAINTAINING or debugging any of it: 3D view, Qt3D usage, sun path or solar position math, shadow projection/casting, shade or hours-of-sun heatmaps, object height property, seasonal/time-of-day sun animation, first-person walkthrough, or growth visualization. It is a reference, NOT a plan — its "TO BUILD" markers are historical and that code already exists. Also load when someone says "sun study", "shade map", "solar", "azimuth", "elevation angle", "shadow length", "height of fence/wall/tree", or asks which 3D engine to use. Contains verified repo asset inventory, the NOAA solar formulas with pinned reference numbers, Y-axis discipline for azimuth→scene conversion, and GO/NO-GO gates for the 3D engine spike.

The load-bearing architecture contract for Open Garden Planner: the invariant table, the module dependency map, the command-pattern write path, and the known weak points. Load this BEFORE designing any feature, adding a module or package, or touching serialization (.ogp / FILE_VERSION), undo/redo, layers, beds/containers/plant-parents, task status, plant sizing, rotation/resize geometry, or the agent_api (MCP) surface — and whenever you are asking "is this allowed architecturally?", "does an ADR already cover this?", or "which predicate / write path / chokepoint do I use?". Also load it before reviewing someone else's design.

Load when doing anything outward-facing for Open Garden Planner: writing or editing the README, release notes, announcements, wiki pages, or any public claim about capabilities; adding or upgrading a dependency (license-compatibility check); integrating or documenting an external service (Google Maps, plant APIs, weather); answering licensing questions (GPLv3, PyQt6, asset/texture licensing); positioning the project against other tools; or publishing benchmarks / accuracy claims. This skill is the anti-oversell guardian — it defines what may be claimed today, what must not be, and the trust obligations (checksums, unsigned installer, CI-owned releases) that come with every release.

The ambition map for Open Garden Planner — five open research/engineering frontiers where THIS project could advance the state of the art, each with the verified in-repo asset that makes it credible, the first three concrete steps, and a falsifiable "you have a result when…" milestone. Load this when: picking the next big direction; evaluating whether an idea is genuinely novel or already solved elsewhere; scoping Package D2/D3 (agent write tools, domain intelligence) or Phase-15+ ambitions (visual refresh, Phase 16 platform work); someone asks "what should this project do next" or "where is the frontier here"; or you are about to resurrect a retired idea and need to check whether it was deliberately killed. Everything in here is OPEN or CANDIDATE work — nothing in this file is shipped unless explicitly marked as an existing asset.

Evidence-based debugging via targeted verbose instrumentation. Apply at the first sign of any non-obvious bug — before theorising. Grows with each bug fixed in this project.

Catalog of every configuration axis in Open Garden Planner: QSettings keys (AppSettings), UI-state persistence (UiStateStore), environment variables (.env / OGP_GOOGLE_MAPS_KEY / QT_QPA_PLATFORM / PYTHONUTF8), project-file version + per-plan settings, hidden-feature toggles in code, tooling config (pyproject/ruff/mypy/pytest/pins/ogp.spec), and CI knobs. Load this when: adding or changing a setting or flag; wondering what a settings key does or what its default is; configuring environment variables or .env; touching the Preferences dialog; deciding whether a change needs a FILE_VERSION bump; or a feature seems mysteriously disabled (hidden panel, missing API key, default-off snap mode). Includes the "how to add a setting" checklist.

Fast symptom→cause→experiment triage for Open Garden Planner's recurring failure modes. Load this when: a bug is reported (by a user, manual tester, or reviewer); a test fails unexpectedly; CI is red while local is green (or vice versa); a test passes alone but fails in the full run; behaviour differs from what the code appears to do; a visual glitch appears on the canvas (mirrored text, ghost shapes, items drifting/jumping, handles that won't drag); an export (PNG/SVG/PDF/DXF) looks wrong or empty; the German UI shows English or mojibake; panels go stale or steal focus; the packaged exe crashes or a bundled service silently fails. This skill classifies the symptom against the project's hard-won pitfall chronicle so you fix from precedent instead of re-fighting a solved bug.

Dev-time discipline for adding or regenerating Open Garden Planner textures and 2D art (US-E9, #264). Load when: adding a fill-pattern texture; regenerating a texture (e.g. the known-seamed flagstone.png/glass.png); generating object art or 3D-era materials; choosing texture prompts/post-processing; or answering how assets get provenance and license clearance. The skill prescribes the house style, the mechanical tileability gate, and the provenance rules — assets without provenance don't merge.

Environment setup, running, building, and packaging Open Garden Planner. Load this skill when: setting up the dev environment from scratch (Windows or Linux/CI/cloud), running the app or the test suite, building the PyInstaller exe or the NSIS installer, adding or bumping a dependency, hitting an ImportError / ModuleNotFoundError / frozen-exe startup failure, wondering where artifacts, autosaves, settings, or user data land on disk, or checking whether the embedded Agent API (MCP) server is up.

Load BEFORE starting any change to Open Garden Planner — feature, bug fix, refactor, doc-in-code, or chore — and whenever you are about to branch, commit, open a PR, mark a PR ready, merge, bump a version, create/wait on a release, or you are wondering whether an action (tagging, pushing to master, merging without user sign-off, skipping a test or translation) is allowed. Explains how changes are classified (US / issue / chore), every non-negotiable gate with the historical incident behind it, the CI release machinery (release.yml / ci.yml), and a start-to-finish change checklist. If you are unsure whether a gate applies to you, it does — read this first.

Catalogue of every diagnostic instrument in Open Garden Planner, with interpretation guides — how to MEASURE instead of eyeball. Load when you need to: verify a claim about behavior, measure what the code actually does, run or interpret quality gates (pytest / ruff / bandit / mypy / i18n gate), inspect a LIVE running plan via the Agent API (MCP on 127.0.0.1:8765), check translations or exports, detect mojibake, trace a geometry bug numerically, find when/why something changed in git history, smoke-test the built exe, or simply choose the right instrument for an investigation. Also load when a pytest run shows "Fatal Python error: Aborted", "passes alone fails together", or you're unsure what a gate can and cannot catch.

Load when finishing ANY feature or fix in Open Garden Planner and you owe documentation updates (you always do — this project practices continuous documentation); when writing an ADR, an FR-* entry, a §11.4 pitfall entry, or a debug-verbose case study; when updating docs/roadmap.md, docs/functional-requirements.md, or CLAUDE.md progress tables; when syncing the GitHub wiki; or whenever you are unsure WHERE a piece of knowledge should live in the docs. Contains the verified docs-of-record map, the mandatory change-type → doc-target tables, the house style derived from real entries, and copy-pasteable templates for every document type. The docs are this project's institutional memory — every change must leave them better than found.

The chronicle of every major OGP investigation, dead end, rejected fix, and revert — so nobody re-fights a settled battle. Load this skill when: (1) you are about to change a subsystem that has history (rotation/resize, properties panel, undo stack, task status, sidebar lists, exception handling at file-load, release workflow, installer, i18n, Agent API render); (2) a bug you're chasing resembles something described here; (3) you are tempted to "fix" code that looks wrong (a broad `except Exception`, a debounce plus a flush queue, a `rect().center()` pivot, a write-only `task_completions` mirror — it may be the scar of a fixed bug); or (4) you're investigating WHY code is written in a strange way. Fast triage for a live bug = ogp-debugging-playbook; the invariants as forward-looking contracts = ogp-architecture-contract. This skill records how those invariants were learned, the hard way.

Gardening/horticulture domain knowledge pack for Open Garden Planner — as encoded in THIS codebase, not a gardening textbook. Load when: touching species data, plants, beds/containers/trellises, soil tests/amendments, companion planting, spacing, tasks/calendar, succession, crop rotation, harvest logs, frost/weather, propagation, or seed inventory; when you need to know what a diagnostic (antagonist badge, spacing overlap, soil mismatch, capacity overrun) means agronomically and where it is computed; when you need the canonical species_key rules, the plant-sizing precedence, the Rapitest soil scale, or the meaning of a domain term (brassica, hardiness zone, amendment, succession). Also load before adding any bed/container feature or editing bundled JSON data files.

First-principles proof methods for Open Garden Planner — how this project verifies claims instead of assuming them. Load when: you are about to assert something about a third-party library's behavior (mcp/FastMCP, PyQt6, Qt geometry, numpy); you are about to write or trust geometry/transform code (rotation, resize, coordinate frames, serialization invariants); you are choosing a tolerance, threshold, or epsilon; two coordinate frames (scene vs pixel, local vs scene) might disagree; a reviewer or doc claims something about the code and you're deciding whether to act on it; you're designing tests for a class of inputs (shapes × angles × handles) or hardening a trust boundary against hostile files; or any claim needs proof before it goes into a PR, ADR, or doc. Theme: "prove it, don't just install it."

Domain-theory knowledge pack for Qt Graphics View + CAD geometry as used in Open Garden Planner. Load when: touching canvas items or tools, anything involving coordinates or the Y-flip, rendering/export (PNG/PDF/SVG/DXF/agent render tool), rotation/resize/transformOriginPoint, snapping or the constraint solver, drag handles / ItemIgnoresTransformations, curves and arcs, scene/signal lifecycle bugs, or writing Qt tests (qtbot, QTest, tool.mouse_press). Teaches the mental models a zero-context engineer lacks; every claim is grounded in this repo's source and docs.

The discipline that turns a hunch into an accepted result in Open Garden Planner. Load this when: starting any investigation (bug, performance question, design doubt); forming a hypothesis about why something behaves the way it does; deciding whether the evidence you have is sufficient to adopt a change; tempted to declare a fix "done" after a green test run; planning an experiment or instrumentation pass; a senior-review finding contradicts your understanding; or a manual test contradicts your green tests. Encodes the project's evidence bar, prediction-before-experiment rule, adversarial review culture, manual-test sovereignty, the idea lifecycle from hunch to docs-of-record (or documented retirement), and the named anti-patterns this project has already paid for.

What counts as EVIDENCE in Open Garden Planner and how to produce it. Load when: writing or placing any test (unit/integration/ui); deciding whether a piece of work is "done"; preparing a PR or a manual-testing checklist; judging whether test results suffice as proof; a reviewer or the user asks "how do you know this works?"; pinning a bug fix with a regression test; adding a bed/plant-parent feature (golden parametrised gate must be extended); or a test passes alone but fails in the full run. Covers the evidence hierarchy (CI floor → senior-reviewer → manual-test sovereignty), the §8.10 integration-test policy, regression-pinning discipline, the full quality-gate battery and the CI-vs-local gate split, and manual-test checklist standards.

End-of-user-story procedure — commit, push, PR, merge, version bump, roadmap update, wiki sync, branch cleanup

Analyze a GitHub PR for the open-garden-planner repo — fetch metadata + linked issues, check out the branch, run every test layer the agent can run locally (pytest unit/integration/ui, ruff, bandit, i18n gate, PyInstaller exe smoke), then produce a copy-paste-ready manual-test plan for whatever's left. Invoke with a PR number ("analyze-pr 191"), with no argument (auto-pick if exactly one open PR), or on the current branch ("analyze-pr current").