# 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.