Jon Chery
103 lines
4.0 KiB
Markdown
103 lines
4.0 KiB
Markdown
# 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. |