82 lines
4.0 KiB
Markdown
82 lines
4.0 KiB
Markdown
# PROMETEU Learn
|
|
|
|
This area contains pedagogical material about the PROMETEU machine.
|
|
|
|
It exists to explain the fantasy handheld's mental model, influences, tradeoffs, and design implications without contaminating the normative specs with pedagogical framing.
|
|
|
|
## Authority
|
|
|
|
- `docs/runtime/learn/` is not a canonical source of technical contract.
|
|
- The machine's normative surfaces live in [`../specs/`](../specs/README.md).
|
|
- The VM/runtime's internal invariants live in [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md).
|
|
|
|
## Reading Order
|
|
|
|
If someone is entering the machine model now, the most useful order is:
|
|
|
|
1. [`mental-model-time-and-cycles.md`](mental-model-time-and-cycles.md)
|
|
2. [`mental-model-portability-and-cross-platform.md`](mental-model-portability-and-cross-platform.md)
|
|
3. [`mental-model-observability-and-debugging.md`](mental-model-observability-and-debugging.md)
|
|
4. [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
|
5. then the peripherals and specific domains
|
|
|
|
## Core Mental Models
|
|
|
|
- [`mental-model-time-and-cycles.md`](mental-model-time-and-cycles.md)
|
|
- [`mental-model-portability-and-cross-platform.md`](mental-model-portability-and-cross-platform.md)
|
|
- [`mental-model-observability-and-debugging.md`](mental-model-observability-and-debugging.md)
|
|
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
|
|
|
## Peripheral Mental Models
|
|
|
|
- [`mental-model-gfx.md`](mental-model-gfx.md)
|
|
- [`mental-model-audio.md`](mental-model-audio.md)
|
|
- [`mental-model-asset-management.md`](mental-model-asset-management.md)
|
|
- [`mental-model-input.md`](mental-model-input.md)
|
|
- [`mental-model-touch.md`](mental-model-touch.md)
|
|
- [`mental-model-save-memory-and-memcard.md`](mental-model-save-memory-and-memcard.md)
|
|
|
|
## Historical Snapshots
|
|
|
|
These files preserve the rationale of decisions already absorbed by specs and/or implementation. They are useful for context, but they should not be read as the primary current contract.
|
|
|
|
- [`historical-gfx-status-first-fault-and-return-contract.md`](historical-gfx-status-first-fault-and-return-contract.md)
|
|
- [`historical-audio-status-first-fault-and-return-contract.md`](historical-audio-status-first-fault-and-return-contract.md)
|
|
- [`historical-asset-status-first-fault-and-return-contract.md`](historical-asset-status-first-fault-and-return-contract.md)
|
|
- [`historical-game-memcard-slots-surface-and-semantics.md`](historical-game-memcard-slots-surface-and-semantics.md)
|
|
- [`historical-retired-fault-and-input-decisions.md`](historical-retired-fault-and-input-decisions.md)
|
|
|
|
## Naming Convention
|
|
|
|
- `mental-model-*.md`: consolidated pedagogical entry point.
|
|
- `historical-*.md`: historical snapshot, retired rationale, or material consolidated elsewhere.
|
|
- `README.md`: area map and navigation.
|
|
|
|
## Rules
|
|
|
|
- material in `learn` may explain, compare, teach, and provide context;
|
|
- material in `learn` must not redefine the normative contract of the specs;
|
|
- when a topic has both a spec and a pedagogical guide, the guide should point to the corresponding spec;
|
|
- when there is both a historical snapshot and a consolidated guide for the same topic, the consolidated guide should be the entry point;
|
|
- snapshots must make clear that they are historical and point to the current normative anchors.
|
|
|
|
## When To Create A Pair
|
|
|
|
Create a `spec` + `learn` pair when the topic:
|
|
|
|
- needs a stable technical contract and a mental model;
|
|
- has strong historical, pedagogical, or design-rationale weight;
|
|
- risks turning into manifesto text inside the normative spec;
|
|
- requires examples, comparisons, or intuition that do not belong in the contract.
|
|
|
|
If the topic is small and strictly contractual, the chapter may live only in `specs`.
|
|
|
|
## Learn Refactoring Rule
|
|
|
|
When `learn` accumulates too many snapshots:
|
|
|
|
- consolidate repeated ideas into larger pedagogical guides;
|
|
- reduce chronological redundancy;
|
|
- keep snapshots only as historical trace and backlink;
|
|
- reorganize by mental model, not by decision order.
|