91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
---
|
|
id: LSN-0001
|
|
ticket: legacy-runtime-learn-import
|
|
title: PROMETEU Learn
|
|
created: 2026-03-27
|
|
tags: [migration, tech-debt]
|
|
---
|
|
|
|
# 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
|
|
|
|
- `discussion/lessons/` 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`](../../vm-arch/ARCHITECTURE.md).
|
|
|
|
## Reading Order
|
|
|
|
If someone is entering the machine model now, the most useful order is:
|
|
|
|
1. [`mental-model-time-and-cycles.md`](LSN-0017-mental-model-time-and-cycles.md)
|
|
2. [`mental-model-portability-and-cross-platform.md`](LSN-0014-mental-model-portability-and-cross-platform.md)
|
|
3. [`mental-model-observability-and-debugging.md`](LSN-0013-mental-model-observability-and-debugging.md)
|
|
4. [`mental-model-status-first-and-fault-thinking.md`](LSN-0016-mental-model-status-first-and-fault-thinking.md)
|
|
5. then the peripherals and specific domains
|
|
|
|
## Core Mental Models
|
|
|
|
- [`mental-model-time-and-cycles.md`](LSN-0017-mental-model-time-and-cycles.md)
|
|
- [`mental-model-portability-and-cross-platform.md`](LSN-0014-mental-model-portability-and-cross-platform.md)
|
|
- [`mental-model-observability-and-debugging.md`](LSN-0013-mental-model-observability-and-debugging.md)
|
|
- [`mental-model-status-first-and-fault-thinking.md`](LSN-0016-mental-model-status-first-and-fault-thinking.md)
|
|
|
|
## Peripheral Mental Models
|
|
|
|
- [`mental-model-gfx.md`](LSN-0011-mental-model-gfx.md)
|
|
- [`mental-model-audio.md`](LSN-0010-mental-model-audio.md)
|
|
- [`mental-model-asset-management.md`](LSN-0009-mental-model-asset-management.md)
|
|
- [`mental-model-input.md`](LSN-0012-mental-model-input.md)
|
|
- [`mental-model-touch.md`](LSN-0018-mental-model-touch.md)
|
|
- [`mental-model-save-memory-and-memcard.md`](LSN-0015-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`](LSN-0006-historical-gfx-status-first-fault-and-return-contract.md)
|
|
- [`historical-audio-status-first-fault-and-return-contract.md`](LSN-0003-historical-audio-status-first-fault-and-return-contract.md)
|
|
- [`historical-asset-status-first-fault-and-return-contract.md`](LSN-0002-historical-asset-status-first-fault-and-return-contract.md)
|
|
- [`historical-cartridge-boot-protocol-and-manifest-authority.md`](LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md)
|
|
- [`historical-game-memcard-slots-surface-and-semantics.md`](LSN-0005-historical-game-memcard-slots-surface-and-semantics.md)
|
|
- [`historical-retired-fault-and-input-decisions.md`](LSN-0007-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.
|