Lisa Loop

• The lesson specs you help write
• The AGENTS.md you help configure
• The prompts (PROMPT_plan.md, PROMPT_teach.md)
• The learner's actual code in workspace/
• Git history — commit messages encode which task is active (TASK N - status: description) and git diff shows what the learner changed since last check-in

If the lessons are vague, the AI will teach poorly. If AGENTS.md doesn't have the right compile/run commands, the AI can't validate the learner's work. This conversation is the foundation for the entire learning experience.

Setup

First, initialize the scaffolding in the target project:

scripts/init_lisa.sh /path/to/project

This copies the template files (loop.sh, PROMPT_plan.md, PROMPT_teach.md, AGENTS.md, lessons/) into the project. These files have placeholders that the bidirectional conversation fills in.

Then, guide the user through the bidirectional conversation (see Phase 1 below). During this conversation, you will write the actual files — lessons, AGENTS.md, and PROMPT_plan.md — not just discuss them. By the end of the conversation, all files should be populated and ready.

After the conversation and user review, they run the loops themselves in their terminal:

• ./loop.sh plan — AI generates LEARNING_PATH.md autonomously
• ./loop.sh — AI teaches from the learning path, one activity at a time

Phase 1: The Bidirectional Conversation (What You Do)

This is your entire scope. Do it well.

Step 1: Understand What the Learner Wants

Have a real conversation. Don't accept "I want to learn Rust" and start writing lesson specs. Dig in:

• What do you want to learn? Be specific. "Rust" is a language — what about Rust? Systems programming? Web servers? CLI tools? Game engines?
• Why do you want to learn it? Career change? Hobby project? Specific problem to solve? This shapes the practical direction.
• What do you already know? Programming experience? Related languages? Have they tried this before?
• What does success look like? What should they be able to build when they're done?
• Do you have source material? Books, documentation, courses, tutorials they want to learn from? These go in materials/ and the AI will teach from them.
• How do you learn best? Building projects? Solving puzzles? Understanding theory first? Small exercises?

Push back on vague answers. Surface ambiguities. The user often has context in their head that hasn't been articulated — your job is to draw it out.

Step 2: Identify Learning Goals

Through conversation, identify the core things the learner needs to master. These are outcomes, not topics:

• "Write a Rust program that reads a file, processes the data, and writes output"
• "Understand ownership and borrowing well enough to fix compiler errors independently"
• "Build a simple web API using functional programming patterns"

Step 3: Break Into Lesson Topics

Each learning goal gets broken into focused topics. Each topic should be expressible in one sentence without "and". If you need "and", it's two topics.

Good: "Rust ownership and move semantics" Bad: "Rust ownership and error handling" (split these)

Activity scoping — CRITICAL: Each topic will produce multiple atomic activities in the learning path. Each activity = ONE practical exercise the learner completes. Think about how topics decompose into hands-on practice:

"Rust ownership" becomes: "Move a String between variables", "Write a function that takes ownership", "Fix a program with use-after-move errors", etc.

If a topic is so broad it can't decompose into 3-8 focused activities, it's too big — split it.

Step 4: Source Material (Encourage This)

Actively ask about and encourage source material:

• Books: "Are you reading The Rust Book? A specific chapter?" Drop relevant excerpts into materials/
• Documentation: Official docs, API references, tutorials
• Courses: Video course notes, slide decks
• Custom content: The user might have notes, blog posts, or code they want to learn from

Source material is optional but encouraged. The AI can teach from its own knowledge for well-known topics. But for broader, specific, or exotic topics that might not be well-represented in training data, source material dramatically improves teaching quality.

Help the user organize material into materials/ with clear naming.

Step 5: Write Lesson Specs (One Per Topic)

For each topic, write a lessons/FILENAME.md. Each lesson should cover:

• Learning objectives (what the learner will understand after)
• Prerequisites (what they need to know first)
• Key concepts (what the AI should teach)
• Source material references (files in materials/ to draw from)
• Practice direction (what kind of exercises would teach this topic)

Write lessons collaboratively. Draft them, present to the user, incorporate feedback. A lesson the user hasn't reviewed is a lesson that might misrepresent what they want to learn.

Use the lesson template at assets/templates/lesson.md as a starting point.

Step 6: Configure AGENTS.md

AGENTS.md is the operational guide loaded every teaching iteration. Set it up together with the user:

• Language & Tools: What language? What compiler/interpreter version? What editor?
• Validation: How to compile and run the learner's code. This is critical — the AI needs to check if the learner's work actually works. Ask for the exact commands.
• Source Material: Paths to reference material in materials/ if any.
• Learning Preferences: Learner's current level, preferred style.
• Operational Notes: OS, environment quirks, anything the AI should know.

Keep AGENTS.md concise — it gets loaded into every iteration's context.

Step 7: Configure PROMPT_plan.md

Help the user fill in the [learning-specific goal] in PROMPT_plan.md. This should capture the full learning objective, e.g.:

"Teach the learner Rust programming with a focus on systems-level concepts (ownership, borrowing, lifetimes) and functional programming patterns (iterators, closures, pattern matching). Build toward a small CLI tool that processes text files. The learner knows Python and JavaScript but has no systems programming experience."

Step 8: Encourage Review

Before the user runs the loops, actively encourage them to:

1. Read every lesson spec — Do they capture what you actually want to learn?
2. Review AGENTS.md — Are the compile/run commands correct?
3. Review PROMPT_plan.md — Does the goal capture your learning vision?
4. Check materials/ — Is the source material organized and accessible?

Say something like: "Before you run ./loop.sh plan, read through the lessons and AGENTS.md. The teaching AI uses these as its only guide — if something's wrong or missing here, the teaching will reflect that. If anything needs adjustment, we can refine it."

Re-invocation for Refinement

The user may invoke this skill again to:

• Refine or expand existing lessons
• Add new topics they want to learn
• Add source material they found
• Adjust AGENTS.md based on environment changes
• Redirect the learning journey based on what they've experienced

This is expected and good.

What Happens After (NOT Your Job)

For reference only — you do NOT execute these phases:

Phase 2: Planning (./loop.sh plan) — The user runs this in their terminal. The AI studies lessons + materials, creates LEARNING_PATH.md with atomic practical activities. Usually 1-2 iterations.

Phase 3: Teaching (./loop.sh) — The user runs this in their terminal. Each iteration: read learning path, pick activity, check learner's workspace progress, teach the concept, guide the exercise, evaluate completion, write marker. The loop waits (default 2 minutes) for the learner to work, then starts a new iteration to check progress.

The user can also run ./loop.sh --done to skip the wait when they've finished an activity and want immediate validation.

Key Design Decisions

For detailed concepts, see references/concepts.md.

• The learner types the code. Lisa NEVER writes into workspace files. The whole point is building neural pathways through practice, not offloading learning to AI.
• Git as memory. Each iteration reads git log (structured commit messages: TASK N - status: description) to know which task is active, and git diff to see what the learner changed. This bridges fresh-context iterations — the AI never loses track of progress.
• Code doesn't need to compile. Unlike Ralph Loop, broken code is expected and valuable. Compilation errors are teaching moments. Commits capture the learner's state, whatever that state is.
• AGENTS.md provides validation commands so Lisa can check if the learner's code compiles/runs. This is informational backpressure — errors help the AI teach, they don't block progress.
• Fresh context per iteration means Lisa re-reads the learner's progress each time via git diff. No stale assumptions.
• The wait timer gives the learner time to work. Lisa teaches, then steps back. The learner practices. Lisa comes back to check.
• Source material in materials/ lets the AI teach from specific books, docs, or content the learner wants to study — extending beyond the AI's training data.
• PROMPT_plan.md and PROMPT_teach.md use deliberate language patterns ("study", "Ultrathink") and the escalating 9s guardrail pattern. Preserve these when customizing.
• Learning path is disposable — delete LEARNING_PATH.md and rerun ./loop.sh plan anytime.