glassbox / rules

---
description: Hot Sheet — ticket-driven work, testing, and requirements-doc conventions
alwaysApply: false
---

<!-- hotsheet:begin section=ticket-driven-work v=1 -->
## Ticket-Driven Work

When the user gives you work directly (not via the Hot Sheet channel or events), create Hot Sheet tickets before starting implementation — especially for substantial or multi-step work.

- **Do create tickets** for: features, bug fixes, refactoring, multi-step tasks, anything changing code. **Don't** for: simple questions, git commits, quick lookups, trivial one-liners. **When in doubt, create them.**
- Create via the Hot Sheet API (prefer the `hotsheet_*` MCP tools), mark Up Next, then work through them: set status `started` → implement → set `completed` with notes.
- **Always create follow-up tickets** for incomplete work (unfinished steps, open design questions, known gaps, designed-but-unbuilt features). If it's not in a ticket, it's forgotten.
- **Incomplete-work checklist** — before marking a ticket `completed`, file follow-ups for any: (1) UI placeholder text ("coming soon"), (2) TODO/FIXME comments, (3) documented-but-unimplemented requirements, (4) empty/stub functions returning mock data.
- **Use FEEDBACK NEEDED before deferring or asking about follow-ups.** When about to (a) defer a ticket needing more work, (b) ask whether to file follow-ups, or (c) close with a question buried in notes — DON'T. Leave the ticket `started`, add a `FEEDBACK NEEDED:` note (per `.hotsheet/worklist.md`), signal channel done, and wait. It's the only reliable way to surface a question.
<!-- hotsheet:end section=ticket-driven-work -->

<!-- hotsheet:begin section=testing-philosophy v=2 -->
## Testing Philosophy

- **Double coverage**: every feature covered by both unit tests AND E2E tests. Unit = logic in isolation; E2E = real user flows through the running app with minimal mocking.
- **Unit tests**: Mock external deps (filesystem, network), test real logic.
- **E2E tests**: As much as possible, use test automation tools to run realistic, user-facing flows. Minimize mocks.
- **Coverage**: Merge all test coverage (e.g. unit, E2E server, E2E browser) into one report. Low-coverage files should get more of both test types. Aim for 100% coverage of code lines, 100% coverage of branches, and 100% of features described in the requirements documentation.
- **Coverage is a floor, not a ceiling**: 100% line/branch coverage shows every line *ran*, not that every *behavior* — or every *sequence* of behaviors — is *asserted*. It is structurally blind to a **missing state transition**: a bug living in an untested interaction sails through a green 100% report because the individual lines still get hit by isolated, single-operation tests.
- **Transition-matrix testing for stateful modules**: for anything with modes / multiple code paths / a cache / a state machine, enumerate the states AND the transitions between them, then write tests that walk realistic multi-step sequences crossing state boundaries — not just each operation from a clean initial state.
- **Adversarial pass on stateful changes**: when adding or altering a stateful code path, deliberately try to break it with out-of-order / interleaved / repeated / empty-then-refill sequences; pin any that would have failed as permanent regression tests.
- **Manual test plan**: keep a manual test plan doc (e.g. `docs/manual-test-plan.md`) for features that can't be reliably automated. **Keep it up to date** — add such features there; when you add automated coverage for a previously-manual item, remove it and note it in an "Automated Coverage Summary".
- **Always fix lint and type errors before finishing**: Fix as you go, don't batch.

<!-- hotsheet:begin specifics=testing-philosophy v=1 -->
### This project's test setup
<!-- hotsheet:needs-setup -->

> ⚙️ **Setup needed — fill this in once.**
> The test specifics for this project haven't been recorded yet. The next time you (an AI assistant) are about to write tests, run tests, or set up CI:
> 1. **Detect** what you can from the project's config (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, CI files).
> 2. **Ask the user to confirm and fill gaps** — especially tools they *plan* to use but haven't installed yet: the unit and E2E/integration test runner(s); where tests live (paths/globs); the commands to run unit tests, E2E tests, and a merged coverage report; and any shared test helpers to always use.
> 3. **Replace everything between the two `hotsheet:specifics` markers** (including the `hotsheet:needs-setup` line above) with the filled-in specifics, e.g.:
>    - **Unit tests** (`<glob>`): `<runner>`. `<helpers>`.
>    - **E2E tests** (`<glob>`): `<framework>`. `<how they run>`.
>    - **Commands**: unit `<cmd>` · E2E `<cmd>` · coverage `<cmd>`.
>
> Once the `hotsheet:needs-setup` line is gone, this prompt won't appear again.
<!-- hotsheet:end specifics=testing-philosophy -->
<!-- hotsheet:end section=testing-philosophy -->

<!-- hotsheet:begin section=requirements-documentation v=1 -->
## Requirements Documentation

Keep human-readable requirements documents as the source of truth for what the project does, and **keep them up to date in the same change as the code** (add/remove/modify a requirement → update its doc). Create new docs for major new functional areas. Cross-reference related docs with relative links.

### AI Summaries

Maintain two synthesis docs an AI assistant reads at the start of a fresh session — keep them in sync with reality (source doc/code wins on conflict), and prefer small targeted edits over rewrites:

- A **codebase map** — directory tree, entry points, data schema, build, tests, settings, and a "where do I look for X" index. Update it in the same change when you add a file or directory, add a route/endpoint, change the schema, add a client module, or add a setting key.
- A **requirements summary** — a synthesized view of every requirements doc with status markers (e.g. Shipped / Partial / Design only / Deferred). Update it in the same change when you add a requirements doc, ship a design-only feature, or defer/regress a shipped one.

<!-- hotsheet:begin specifics=requirements-documentation v=1 -->
### This project's docs layout
<!-- hotsheet:needs-setup -->

> ⚙️ **Setup needed — fill this in once.**
> Where this project keeps its requirements docs and AI-summary files hasn't been recorded yet. The next time you (an AI assistant) work with the docs:
> 1. **Detect** the existing docs layout (e.g. a `docs/` folder, a wiki, numbered files) and whether codebase-map / requirements-summary files already exist.
> 2. **Ask the user to confirm** the docs location, the file-naming convention, and the exact paths of the codebase-map and requirements-summary files (create them if they don't exist and the user wants them).
> 3. **Replace everything between the two `hotsheet:specifics` markers** (including the `hotsheet:needs-setup` line above) with the filled-in specifics — the docs folder, the naming convention, and the two summary-file paths.
>
> Once the `hotsheet:needs-setup` line is gone, this prompt won't appear again.
<!-- hotsheet:end specifics=requirements-documentation -->
<!-- hotsheet:end section=requirements-documentation -->