Lesson gen

Lesson Generation

Generate lessons for engineering concepts that the developer has not yet mastered. Every lesson uses real code examples from the current repository.

Configuration

Read config.json from the ai-dev-os skill directory. If configured is false or the file is missing, STOP and tell the user:

"Please run /configure-ai-dev-os to set up your Obsidian vault path and Linear team."

• Obsidian vault: Use the obsidian_vault_path value from config.
• Lesson folder: lessons/
• Lesson template: templates/lesson.md
• Confidence threshold: 0.8 (concepts below this get lessons)

Input

Concept extraction report from knowledge-extract stage, filtered to concepts with disposition "new" or "weak" (confidence < 0.8).

Skip Condition

If all detected concepts have confidence >= 0.8 in Obsidian, skip this stage. Output:

Lesson generation skipped: all detected concepts have confidence >= 0.8.

Procedure

Step 1: Filter concepts needing lessons

From the extraction report, select concepts where:

• Disposition is "new" (no existing note, confidence = 0.0)
• Disposition is "weak" (existing note with confidence < 0.8)
• Concept is important to understanding the ticket

Step 2: For each concept, generate a lesson

1. Read template: Call mcp__obsidian__obsidian_read_note on templates/lesson.md.

2. Populate the lesson:

   • Title: {{Lesson Title}} -> e.g., "Understanding Retry Backoff"
   • Why You Need This: Why this concept matters for the developer's work. Reference the current ticket.
   • What You Should Already Know: List prerequisite concepts. Check if those prerequisites exist in Obsidian — if not, note them as gaps.
   • Intuitive Explanation: Explain the concept using analogies, everyday language, mental models. No jargon.
   • Formal Explanation: Precise technical definition with correct terminology.
   • Step-by-Step Breakdown: Numbered walkthrough of how the concept works, step by step.
   • Code Example From This Repo:
     • File: exact file path from the diff
     • Lines: exact line range
     • What it does: explanation of how the code demonstrates the concept
   • Pitfalls: Common mistakes when implementing or using this concept.
   • Exercises: 2-3 practice prompts the developer can try.
   • Questions to Check Understanding: 2-3 questions to self-assess comprehension.

3. Set frontmatter:

   • topic = concept name
   • difficulty = estimated 1-5
   • confidence_target = 0.8
   • prerequisites = list of prerequisite concept names
   • related_concepts = [[links]] to concept notes
   • related_files = file paths from the code example
   • related_lines = line ranges from the code example
   • created = today (ISO 8601)
   • updated = today
   • source_ticket = ticket ID

4. Write lesson: Call mcp__obsidian__obsidian_update_note to create lessons/<concept-slug>_lesson.md.

5. Link to concept note: Use mcp__obsidian__obsidian_search_replace on the concept note to add a link to the lesson under "## See Also".

Step 3: Create ticket learning summary

1. Read template: Call mcp__obsidian__obsidian_read_note on templates/ticket_summary.md.

2. Populate:

   • {{Ticket ID}} = ticket ID
   • Ticket Goal = from ticket-intake
   • What Changed = summary of code changes
   • Key Concepts = list of all detected concepts with [[links]]
   • New Knowledge = what was learned from this ticket
   • Follow-up Questions = open questions or areas for deeper study
   • Related Notes = links to all created/updated notes

3. Write: Call mcp__obsidian__obsidian_update_note to create tickets/<ticket-id>-learning-summary.md.

Gotchas

• Requires templates/lesson.md and templates/ticket_summary.md in the Obsidian vault. Verify they exist during pre-flight.
• Code examples reference specific file:line locations that may become stale. Lessons are most valuable when reviewed shortly after creation.
• If all concepts have confidence >= 0.8, this stage is skipped entirely — this is expected behavior, not an error.

Output

Summary of lessons generated:

## Lesson Generation Summary

### Lessons Created
| Concept | Lesson Path | Difficulty | Prerequisites |
|---------|------------|------------|---------------|

### Ticket Summary
- Created: tickets/<ticket-id>-learning-summary.md

### Prerequisite Gaps
| Prerequisite | Status |
|-------------|--------|