117 lines
3.0 KiB
Markdown
117 lines
3.0 KiB
Markdown
# Packer Documentation
|
|
|
|
This directory contains the working, planning, and normative documentation for the `packer` domain.
|
|
|
|
`packer` is a standalone domain. It follows the same documentary cycle used elsewhere in the repository:
|
|
|
|
`agendas -> decisions -> pull-requests -> specs -> learn`
|
|
|
|
## Tree
|
|
|
|
```text
|
|
docs/packer/
|
|
├── agendas/
|
|
├── decisions/
|
|
├── learn/
|
|
├── pull-requests/
|
|
├── specs/
|
|
├── Prometeu Packer.md
|
|
└── README.md
|
|
```
|
|
|
|
## Responsibilities
|
|
|
|
### `Prometeu Packer.md`
|
|
|
|
`Prometeu Packer.md` is the current bootstrap specification for the domain.
|
|
|
|
Use it to:
|
|
|
|
- understand the current packer scope,
|
|
- recover the initial architecture and terminology,
|
|
- seed the split into smaller normative specs under `specs/`.
|
|
|
|
This document is useful as a draft source, but it should not become a permanent dumping ground for every future change.
|
|
|
|
### `agendas/`
|
|
|
|
`agendas/` contains open packer topics.
|
|
|
|
Use it to:
|
|
|
|
- frame unresolved problems,
|
|
- compare options and tradeoffs,
|
|
- define scope and non-goals,
|
|
- drive discussions toward a decision.
|
|
|
|
An agenda is a discussion artifact, not a final contract.
|
|
|
|
### `decisions/`
|
|
|
|
`decisions/` contains closed packer decision records.
|
|
|
|
Use it to:
|
|
|
|
- record the chosen direction,
|
|
- capture constraints and invariants,
|
|
- state what remains intentionally out of scope,
|
|
- identify which specs, plans, or code paths must be updated.
|
|
|
|
Decisions close debate. They are not brainstorming notes.
|
|
|
|
### `pull-requests/`
|
|
|
|
`pull-requests/` contains self-contained execution proposals.
|
|
|
|
Use it to:
|
|
|
|
- package a change for review,
|
|
- plan propagation across specs and implementation,
|
|
- define acceptance criteria,
|
|
- make tests and risks explicit before editing code or final specs.
|
|
|
|
### `specs/`
|
|
|
|
`specs/` contains the normative packer corpus.
|
|
|
|
Use it to:
|
|
|
|
- consolidate the official packer contract,
|
|
- split large draft material into stable chaptered specs,
|
|
- define behavior, constraints, interfaces, and conformance expectations.
|
|
|
|
Specs should only absorb already-closed decisions.
|
|
|
|
### `learn/`
|
|
|
|
`learn/` contains didactic consolidation.
|
|
|
|
Use it to:
|
|
|
|
- explain why the packer works the way it does,
|
|
- preserve hard-won operational knowledge,
|
|
- teach future contributors the model, pitfalls, and expected workflows,
|
|
- reorganize accumulated knowledge into a cleaner learning surface.
|
|
|
|
`learn/` is not an archive of old decisions.
|
|
|
|
## Recommended Flow
|
|
|
|
The preferred packer documentation flow is:
|
|
|
|
1. `agendas/`: open and shape the unresolved topic.
|
|
2. `decisions/`: close the architectural choice.
|
|
3. `pull-requests/`: plan how the decision will be propagated.
|
|
4. `specs/`: integrate the decision into normative text.
|
|
5. `learn/`: consolidate the final knowledge in a didactic form.
|
|
|
|
## Practical Rule
|
|
|
|
- `agendas/` stores open questions.
|
|
- `decisions/` stores closed answers.
|
|
- `pull-requests/` stores execution plans.
|
|
- `specs/` stores the normative packer contract.
|
|
- `learn/` stores teaching-oriented consolidation.
|
|
|
|
If implementation exposes a missing architectural choice, stop and return to `agendas/` or `decisions/`.
|