Learning Loop - GEARS System

Autonomous structured learning for mastering complex topics through cron-based 5-session feedback loops. Use when user wants to deeply learn a subject (e.g.,...

Learning Loop — The GEARS System

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

Phase	Session	What Happens
Gather	S1	Research concepts, create test questions
Execute	S2	Take the test blind, document failures
Analyze	S3	Diagnose why you failed, research solutions
Retry	S4	Apply fixes, measure improvement
Synthesize	S5	Validate mastery, adjust schedule

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 <skill-dir> 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)

GEARS	Session	What	Key Output
Gather	S1	Research subtopic, create 10-15 test questions WITH answers	s1-research.md
Execute	S2	Answer questions blind (no peeking), score objectively	s2-test.md, s2-failures.md
Analyze	S3	Diagnose each failure, research gaps specifically	s3-analysis.md
Retry	S4	Re-answer using new understanding, compare scores	s4-retry.md + creates S5 cron
Synthesize	S5	Synthesize, update validated knowledge, decide next subtopic	s5-synthesis.md

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

S4 Score	Action
>= 85%	Mark subtopic mastered, advance to next in curriculum
50-84%	Retry same subtopic tomorrow, focus on remaining gaps
< 50%	Flag for user intervention — topic may need prerequisite work

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 <topic-slug> — 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)