prometeu-studio/docs/packer

Packer Documentation

This directory contains the working, planning, normative, and didactic 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

docs/packer/
├── agendas/
├── decisions/
├── learn/
├── pull-requests/
├── specs/
└── README.md

Responsibilities

agendas/

agendas/ is a transient staging area for 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. When a topic is fully propagated into specs and learn, the corresponding agenda should leave the retained set.

decisions/

decisions/ is a transient staging area for closed packer decisions before full consolidation.

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. Once their content is fully absorbed into specs and learn, they should not be retained just as historical residue.

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 currently open questions only.
• decisions/ stores only decisions that still need propagation.
• pull-requests/ stores execution plans.
• specs/ stores the normative packer contract.
• learn/ stores teaching-oriented consolidation.

The current packer core has already been consolidated into specs/ and learn/. The agendas/ and decisions/ directories remain available for future cycles.

If implementation exposes a missing architectural choice, stop and return to agendas/ or decisions/.