81 lines
3.9 KiB
Markdown
81 lines
3.9 KiB
Markdown
# PROMETEU Learn
|
|
|
|
Esta área reúne material didático sobre a máquina PROMETEU.
|
|
|
|
Ela existe para explicar o modelo mental da fantasy handheld, suas influências, tradeoffs e implicações de design sem contaminar as specs normativas com framing pedagógico.
|
|
|
|
## Authority
|
|
|
|
- `docs/runtime/learn/` não é fonte canônica de contrato técnico.
|
|
- As superfícies normativas da máquina vivem em [`../specs/`](../specs/README.md).
|
|
- As invariantes internas da VM/runtime vivem em [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md).
|
|
|
|
## Reading Order
|
|
|
|
Se a pessoa esta entrando agora no modelo da maquina, a ordem mais util e:
|
|
|
|
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. depois os perifericos e dominios especificos
|
|
|
|
## 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-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
|
|
|
|
Estes arquivos preservam o racional de decisions ja absorvidas por specs e/ou implementacao. Eles sao uteis para contexto, mas nao devem ser lidos como contrato atual primario.
|
|
|
|
- [`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`: ponto de entrada didatico e consolidado.
|
|
- `historical-*.md`: snapshot historico, racional aposentado ou consolidado em outro lugar.
|
|
- `README.md`: mapa e navegacao da area.
|
|
|
|
## Rules
|
|
|
|
- material em `learn` pode explicar, comparar, ensinar e contextualizar;
|
|
- material em `learn` não deve redefinir o contrato normativo dos specs;
|
|
- quando um tema tiver spec e guia didático, o guia deve apontar para o spec correspondente.
|
|
- quando houver snapshot historico e guia consolidado sobre o mesmo tema, o guia consolidado deve ser o ponto de entrada.
|
|
- snapshots devem deixar claro que sao historicos e apontar para as anchors normativas atuais.
|
|
|
|
## When To Create A Pair
|
|
|
|
Criar um par `spec` + `learn` quando o tema:
|
|
|
|
- precisa de contrato técnico estável e também de modelo mental;
|
|
- tem forte carga histórica, pedagógica ou de design rationale;
|
|
- corre risco de virar manifesto dentro do spec normativo;
|
|
- exige exemplos, comparações ou intuição que não pertencem ao contrato.
|
|
|
|
Se o tema for pequeno e estritamente contratual, o capítulo pode nascer só em `specs`.
|
|
|
|
## Learn Refactoring Rule
|
|
|
|
Quando `learn` acumular snapshots demais:
|
|
|
|
- consolidar ideias repetidas em guias didaticos maiores;
|
|
- reduzir redundancia cronologica;
|
|
- manter snapshots apenas como rastro historico e backlink;
|
|
- reorganizar por modelo mental, nao por ordem de decisao.
|