Scope Discipline
The mission: do one thing exceptionally well, focused reading on constrained
hardware. SCOPE.md is the source of truth for what is in and out. Read it
before adding surface. This is the gate to run before writing a new feature.
The gate
Before adding a feature, activity, lib, setting, or dependency, answer in order:
- Is it in
SCOPE.md? Explicitly out: interactive apps (notepad,
calculator, games), active connectivity (RSS, news, browser), media/audio
playback. If it is out, say so and stop.
- Does it materially improve focused reading? If the benefit is
"nice to have" or serves a different use case, it is out. This is not a PDA.
- What does it cost in RAM and in the largest-free-block budget? A feature
that adds steady-state RAM or a large transient allocation needs a reading
benefit that clearly outweighs it. Quantify with
firmware_size_history.py
and script_profile_mem.sh rather than guessing.
- Can it be done with no new code? Prefer an existing activity, an existing
setting, or a doc over a new code path. The cheapest feature is the one
already built.
If a request fails the gate, push back with the specific reason and the
SCOPE.md basis, and offer the in-scope alternative. Make the call and say why;
do not just hand over a menu.
Surface awareness
The firmware already carries dozens of activities. Each new one is permanent
RAM, permanent maintenance, and another thing every future refactor must not
break. Default to extending an existing activity or setting before adding a new
screen. New top-level surface needs a real justification, not "it would be
convenient."
Settings are not free
A new setting is a field to persist, migrate, validate, translate, and render,
plus combinatorial test burden. Add one only when users genuinely need the
choice; otherwise pick a sensible fixed default.
Self-review
1---2name: scope-discipline3description: Feature-scope discipline for a dedicated e-reader (not a Swiss Army knife). Use when adding a feature, a new activity, a new lib, a setting, or a dependency, or when a request would grow the firmware's surface. Covers the SCOPE.md test, the RAM-cost vs reading-benefit gate, preferring no-code or existing-mechanism solutions, awareness of the existing activity surface, and how to push back on out-of-scope asks.4---56# Scope Discipline78The mission: do one thing exceptionally well, focused reading on constrained9hardware. `SCOPE.md` is the source of truth for what is in and out. Read it10before adding surface. This is the gate to run before writing a new feature.1112## The gate1314Before adding a feature, activity, lib, setting, or dependency, answer in order:15161. **Is it in `SCOPE.md`?** Explicitly out: interactive apps (notepad,17 calculator, games), active connectivity (RSS, news, browser), media/audio18 playback. If it is out, say so and stop.192. **Does it materially improve focused reading?** If the benefit is20 "nice to have" or serves a different use case, it is out. This is not a PDA.213. **What does it cost in RAM and in the largest-free-block budget?** A feature22 that adds steady-state RAM or a large transient allocation needs a reading23 benefit that clearly outweighs it. Quantify with `firmware_size_history.py`24 and `script_profile_mem.sh` rather than guessing.254. **Can it be done with no new code?** Prefer an existing activity, an existing26 setting, or a doc over a new code path. The cheapest feature is the one27 already built.2829If a request fails the gate, push back with the specific reason and the30`SCOPE.md` basis, and offer the in-scope alternative. Make the call and say why;31do not just hand over a menu.3233## Surface awareness3435The firmware already carries dozens of activities. Each new one is permanent36RAM, permanent maintenance, and another thing every future refactor must not37break. Default to extending an existing activity or setting before adding a new38screen. New top-level surface needs a real justification, not "it would be39convenient."4041## Settings are not free4243A new setting is a field to persist, migrate, validate, translate, and render,44plus combinatorial test burden. Add one only when users genuinely need the45choice; otherwise pick a sensible fixed default.4647## Self-review4849- [ ] Checked against `SCOPE.md`; not on the out-of-scope list.50- [ ] Stated the concrete reading benefit, not a generic "useful."51- [ ] Named the RAM/size cost (measured, not guessed) and why the benefit wins.52- [ ] Checked whether an existing activity/setting/doc already covers it.53- [ ] New setting (if any) is justified by a real user need, not added54 "just in case."
crosspoint-reader