55 lines
1.5 KiB
Markdown
55 lines
1.5 KiB
Markdown
# Packer Learn
|
|
|
|
This directory contains didactic packer knowledge.
|
|
|
|
## Purpose
|
|
|
|
`learn/` exists to teach, not merely to store historical leftovers.
|
|
|
|
Use it to:
|
|
|
|
- explain packer architecture in a way new contributors can absorb quickly,
|
|
- consolidate conclusions from completed decisions and PRs,
|
|
- document common pitfalls and anti-patterns,
|
|
- connect normative specs to practical reasoning and implementation reality.
|
|
|
|
## What Belongs Here
|
|
|
|
A `learn` artifact should usually include:
|
|
|
|
1. the original problem,
|
|
2. the decision that resolved it,
|
|
3. the implemented or specified final model,
|
|
4. practical examples,
|
|
5. common mistakes and warnings,
|
|
6. links to the relevant specs and PRs.
|
|
|
|
Good `learn` material reduces onboarding time and prevents the same architectural confusion from repeating.
|
|
|
|
## Writing Rules
|
|
|
|
- Prefer didactic structure over chronological accumulation.
|
|
- Explain why the model exists, not only what it is.
|
|
- Keep terminology aligned with packer specs.
|
|
- Refactor older material when the directory starts feeling like a document graveyard.
|
|
|
|
## Refactor Rule
|
|
|
|
This directory should be periodically reorganized for better presentation.
|
|
|
|
If content grows, prefer:
|
|
|
|
- thematic grouping,
|
|
- overview documents,
|
|
- explicit learning paths,
|
|
- and consolidation of duplicated explanations.
|
|
|
|
The goal is a maintainable learning surface, not a passive archive.
|
|
|
|
## Current Learning Path
|
|
|
|
Start here:
|
|
|
|
1. [`mental-model-packer.md`](./mental-model-packer.md)
|
|
2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
|