Topic and Assessment Schema

Relevant Source Files

• examples/Docker Fundamentals.md
• examples/Docker Networking.md
• examples/Docker Volumes.md
• src/cli/adopt.ts
• src/cli/config.ts
• src/cli/review.ts
• src/types.ts
• test/cli-commands.test.ts
• test/types-difficulty.test.ts

The PALEE system utilizes a structured data model to track learning progress, mastery levels, and spaced-repetition schedules for individual topics within a Markdown-based vault. This data is primarily stored as YAML frontmatter within each topic's Markdown file.

1. The Topic Interface

The Topic interface is the central entity in the system, representing a single unit of learning. It encapsulates metadata, pedagogical configuration, and nested objects for mastery and scheduling.

Key Attributes

• palee_schema: An integer versioning the metadata structure (currently 1) src/types.ts#50
• palee_id: A unique identifier generated during adoption, typically following the pattern T-YYYYMMDDTHHMMSS-xxxxsrc/cli/adopt.ts#13-18
• status: Tracks the learning lifecycle (not_started, learning, paused, archived) src/types.ts#54
• difficulty: A normalized categorization of the topic's complexity src/types.ts#55
• dependencies: An array of palee_id strings representing prerequisite topics src/types.ts#56

Topic Data Flow

The following diagram illustrates how natural language concepts map to the Topic code entity during the adopt process.

Natural Language to Code Entity: Topic Adoption

Sources:src/types.ts#49-59src/cli/adopt.ts#13-18src/cli/adopt.ts#53-62

---

2. Four-Pillar Assessment Model

topic_mastery = round((conceptual + practical + debug + 2 * feynman) / 5, 4)

Feynman technique evaluation carries double weighting (40%) to prioritize true conceptual articulation.

Field	Type	Description
conceptual	number	Understanding of theoretical principles (0.0 to 1.0).
practical	number	Ability to apply knowledge in a hands-on context (0.0 to 1.0).
debug	number	Proficiency in identifying and fixing errors in the topic area (0.0 to 1.0).
feynman	number	Ability to explain the topic simply to others (0.0 to 1.0, 40% weight).
assessed_at	string | null	ISO timestamp of the last assessment update.

Sources:src/types.ts#3-9planning/invariants.md#33examples/Docker Fundamentals.md#9-12

---

3. Review (SRS) State

The Review object stores the Spaced Repetition System (SRS) state, implementing the SM-2 algorithm logic. Unlike the assessment pillars, these fields are updated via the palee review command.

SRS Fields

• ease_factor: The multiplier for the next interval (default 2.5, minimum 1.3) src/types.ts#14
• interval_days: The number of days until the next review src/types.ts#12
• repetition: Count of consecutive successful reviews src/types.ts#13
• lapses: Count of failed reviews (quality < 3) on learned topics src/types.ts#15
• last_quality: The most recent recall quality rating (0–5) src/types.ts#16
• last_reviewed_at: A date-only string (YYYY-MM-DD) recording when the topic was last reviewed src/types.ts#17
• due_at: A date-only string (YYYY-MM-DD) indicating when the topic is next due for review src/types.ts#18

Review State Transition Logic

Sources:src/cli/review.ts#73-88src/engine/sm2.ts#80-82src/types.ts#11-19

---

4. Difficulty Normalization

The system provides a robust normalizeDifficulty function to handle varied user inputs from the CLI or roadmap imports, ensuring the internal Difficulty type remains consistent.

Input Type	Input Value	Resulting Difficulty
String	"beginner", "BEGINNER", " 1 "	beginner
String	"intermediate", "2", "3"	intermediate
String	"advanced", "4", "5"	advanced
Number	<= 1	beginner
Number	2 or 3	intermediate
Number	>= 4	advanced
Unknown	null, undefined, "expert"	intermediate (Fallback)

Sources:src/types.ts#29-47test/types-difficulty.test.ts#14-50

---

5. Frontmatter Mapping

When a file is adopted or updated, the paleeData record is serialized into the Markdown frontmatter. The palee adopt command initializes these values to their defaults.

// Initial state during adoption
const paleeData: Record<string, unknown> = {
  palee_id: topicId,      // Generated T-ID
  palee_schema: 1,
  difficulty,             // User provided or 'intermediate'
  depends_on: dependsOn,  // Array of T-IDs
  topic_mastery: 0.0,
  conceptual: 0.0,
  practical: 0.0,
  debug: 0.0,
  feynman: 0.0,
  assessed_at: null,
  ease_factor: 2.5,
  interval_days: 1,
  repetition: 0,
  lapses: 0,
  last_quality: null,
  last_reviewed_at: null,
  due_at: null,
};

Sources:src/cli/adopt.ts#68-86examples/Docker Fundamentals.md#1-20