Learning Loop — The GEARS System

Master complex topics through autonomous cron-based learning using the GEARS feedback loop:

The agent sets up a learning pipeline during an interactive session; isolated cron agents execute the 5 GEARS sessions autonomously using a pre-generated playbook.

Architecture

When the user says "learn X", the agent:

1. Parses topic, researches it, breaks into a curriculum (15-20 subtopics ordered by prerequisites)
2. Generates a self-contained playbook.md — complete instructions for ALL sessions
3. Creates state.json — progress tracker and baton between sessions
4. Shows schedule to user, gets confirmation
5. Creates cron jobs for S1-S4 (S4 creates S5 when it finishes)
6. Done. Cron agents take over.

Critical design: Isolated cron agents have NO skill context. They read ONLY playbook.md + state.json. The playbook must be completely self-contained.

Setup Flow

Step 1: Parse Topic

Extract topic from user input and slugify:

• "learn machine learning" -> machine-learning
• "teach me database design" -> database-design
• "master Docker" -> docker

Slugify: lowercase, hyphens for spaces, strip special chars.

Step 2: Research & Build Curriculum

Use available search tools (web search, Tavily, SerpAPI — try what's available, fall back gracefully) to research the topic. Break into 15-20 subtopics ordered by prerequisites.

Write curriculum to curriculum.md with:

• Subtopic name
• Why it matters
• Prerequisites (which earlier subtopics are needed)
• Estimated difficulty (1-3)

Step 3: Generate Playbook

Generate playbook.md from the template in references/playbook-template.md. This is the most important file — customize it for the specific topic but keep the session execution instructions generic and self-contained.

Target: under 200 lines so isolated agents don't hit token limits.

Step 4: Initialize State

Create the folder structure and initial state.json by running the pipeline creation script. The script is located in this skill's scripts/ directory:

bash <skill-dir>/scripts/create_pipeline.sh <topic-slug> "<Topic Display Name>"

Where is the directory containing this SKILL.md file. The script respects the OPENCLAW_WORKSPACE env var (defaults to ~/.openclaw/workspace). See references/state-schema.md for all state fields.

Step 5: Show Schedule & Confirm

Display to user:

Learning Pipeline: [Topic]

Curriculum: [N] subtopics starting with "[first subtopic]"
Sessions per day: S1 (research) -> S2 (test) -> S3 (analyze gaps) -> S4 (retry) -> S5 (synthesize)

Timing:
  S1: +30 min from now (research + create test questions)
  S2: +4 hours (blind test from memory)
  S3: +8 hours (diagnose failures + research gaps)
  S4: +12 hours (retry with new understanding)
  S5: created by S4 on completion (synthesize + decide next)

Notifications: You'll get updates at S2 (initial score), S4 (retry score), and S5 (summary + next steps).

Confirm to start, or adjust timing/notification preferences.

Step 6: Create Cron Jobs

After user confirms, read ~/.openclaw/cron/jobs.json, append 4 cron jobs (S1-S4) to the jobs array, and write back. The file format is { "version": 1, "jobs": [...] } — always preserve existing jobs. S5 is NOT pre-created — S4 creates it when it completes.

Each cron job entry uses this format:

{
  "id": "learning-[topic]-s[N]-day[DD]",
  "agentId": "main",
  "name": "Learning [Topic] S[N] Day [DD]",
  "enabled": true,
  "createdAtMs": <timestamp>,
  "updatedAtMs": <timestamp>,
  "schedule": {
    "kind": "once",
    "atMs": <calculated_timestamp>
  },
  "sessionTarget": "isolated",
  "wakeMode": "now",
  "payload": {
    "kind": "agentTurn",
    "message": "You are a learning agent. Read this file for complete instructions: memory/learning/[topic-slug]/playbook.md\n\nThen read state.json in the same folder for current session and subtopic.\n\nYour session: S[N]\n\nExecute the session per playbook instructions. Write outputs, update state.json, handle notifications and follow-up crons as specified."
  },
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "<user-configured>"
  }
}

Important: Calculate atMs timestamps based on user-confirmed timing. Default spacing: S1 +30min, S2 +4h, S3 +8h, S4 +12h from setup time.

If the user has notification preferences configured (Telegram, etc.), set delivery accordingly. Otherwise omit delivery and the playbook instructs agents to write notifications to a file.

Session Summary (GEARS)

For full session details, see references/methodology.md.

For the playbook template that gets customized per topic, see references/playbook-template.md.

For the state.json schema, see references/state-schema.md.

Folder Structure (Per Topic)

memory/learning/[topic-slug]/
├── playbook.md           <- Self-contained instructions for cron agents
├── state.json            <- Dynamic progress tracker (baton between sessions)
├── curriculum.md         <- Topic breakdown with subtopics
├── sessions/
│   └── day-NN/
│       ├── s1-research.md
│       ├── s2-test.md
│       ├── s2-failures.md
│       ├── s3-analysis.md
│       ├── s4-retry.md
│       └── s5-synthesis.md
└── knowledge/
    └── validated.md      <- Accumulated mastered knowledge

Scoring & Progression

Curriculum Expansion

When S5 detects currentSubtopicIndex >= curriculum.length - 2:

1. Research advanced topics beyond what's been mastered
2. Write curriculum-preview.md
3. Notify user: "2 topics remaining. Previewing next phase: [topics]. Continue?"
4. On confirmation (or 24h default): append to curriculum, continue

Scripts

• scripts/create_pipeline.sh — Create folder structure + initial state.json
• scripts/check_progress.sh [topic-slug] — Show status of active learning topics

Pause, Resume & Intervention

Pause: User says "pause learning [topic]" → set status to "paused" in state.json, disable pending cron jobs for that topic in jobs.json.

Resume: User says "resume learning [topic]" → set status to "in_progress", read currentSession from state, create cron jobs from the current session onward.

Intervention (score < 50%): When S5 sets status to "needs_intervention":

1. No further crons are created automatically
2. User is notified with the specific subtopic and score
3. User can: adjust curriculum (remove/reorder subtopics), add prerequisite subtopics, or manually set status back to "in_progress" and currentSession to "S1" to retry

When NOT to Use

• Quick overview or summary needed (just answer directly)
• Simple factual question (no learning loop needed)
• User only wants information, not mastery
• Topic too broad without focus (e.g., "learn everything")
• Topic has no clear right/wrong answers (subjective topics don't self-assess well)