atelier/core/reading-order.md

Core — Reading Order

Status: Foundational Audience: New readers (agents and humans). Read after first-principles.md and conflict-resolution.md.

1. The Canonical Order

This is the order in which the framework is designed to be consumed. Following it ensures you build the mental model before the details.

For All Readers

1. core/first-principles.md — The eight axioms. Everything derives from these. Read first, always.
2. core/conflict-resolution.md — How to resolve disagreements between rules. Read second, always.
3. core/reading-order.md — This document. You are here.

For a Specific Task

4. domains/<relevant>/first-principles.md — The domain's ten principles. Read the domain(s) relevant to your task.
5. domains/<relevant>/<topic>.md — The domain's derived topic docs. Read only what your task needs.

For Reference

6. matrix/principles-matrix.md — The full mapping of every domain principle to its core derivation. Consult when a rule's authority is unclear or a conflict arises.
7. MANIFEST.md — The authoritative index of all framework documents. If a document is not here, it is not part of the framework.

For Evaluation

8. review/agent-checklist.md — The pre-completion checklist. Agents run this before finishing a task.
9. review/peer-review-checklist.md — The human review checklist.
10. review/anti-patterns.md — Catalog of known violations.

For Language-Specific Application

11. languages/<lang>.md — How the domain principles apply in a specific language. Read only for the language you are working in.

For Illustration

12. examples/good/* — Worked examples of the framework applied correctly.
13. examples/bad/* — Worked examples of violations, with the breached principles cited.

2. Reading Paths

Path A: New Agent (Pre-Task)

core/first-principles.md
  → core/conflict-resolution.md
    → core/reading-order.md
      → domains/<task-domain>/first-principles.md
        → domains/<task-domain>/<topic>.md
          → review/agent-checklist.md (run before completing)

Estimated time: 15–25 minutes depending on domain depth.

Path B: New Human (Onboarding)

README.md
  → MANIFEST.md
    → core/first-principles.md
      → core/conflict-resolution.md
        → core/reading-order.md
          → one domain of personal interest (e.g., domains/api/first-principles.md)
            → matrix/principles-matrix.md (skim)

Estimated time: 30–45 minutes for a full pass.

Path C: Conflict Resolution

core/conflict-resolution.md (procedure)
  → matrix/principles-matrix.md (look up both rules' derivations)
    → core/first-principles.md (apply precedence)

Estimated time: 5 minutes per conflict.

Path D: Review

review/agent-checklist.md (or peer-review-checklist.md)
  → for each failed checklist item, follow Path C
    → examples/bad/* for the relevant violation pattern

3. What Not to Read First

• Do not start with examples/. Examples illustrate principles you have not yet read.
• Do not start with languages/. Language rules derive from domain rules you have not yet read.
• Do not start with matrix/. The matrix is a reference, not a tutorial.
• Do not skip core/. Everything depends on it.

4. Skipping is Allowed After Core

After reading core/ (the three foundational documents), you may skip freely. The domains are independent of each other. You do not need to read domains/security/ to use domains/api/. You only need the domain relevant to your task.

The one exception: matrix/principles-matrix.md references all domains. You do not need to read all domains to use the matrix, but the matrix is most useful when you have read at least one domain.

5. Versioning

The framework versions as a whole (semantic versioning). A change to core/first-principles.md is a major version. A new domain is a minor version. A new topic doc is a patch. See CHANGELOG.md for the version history.