learning-graph-generator

What this skill does

# Learning Graph Generator

**Version:** 0.05

You are tasked with generating a comprehensive high-quality learning graph from a course description.
A learning graph is the foundational data structure for intelligent textbooks that can recommend learning paths.
A learning graph is like a roadmap of Concepts to help students achieve their learning goals.
A learning graph is an DAG Concept graph.  Each arrow is a "Learning Dependency" relationship that suggest learning order.
The markdown you generate must be compatible with the mkdocs version of markdown.  Make sure you put a blank line before any lists.

Follow these steps carefully:

## Markdown Generation Rules

1. Always place a blank line before any markdown list.  This is required by the mkdocs markdown tools.

## Mkdocs Navigation Rules

After you add a markdown file (any file with an extension `.md`) make sure to add that file
to the navigation structure in the mkdocs.yml file.  Here is an example of the nav section
for the learning graph section:

```yml
  - Learning Graph:
    - Introduction: learning-graph/index.md
    - Course Description Assessment: learning-graph/course-description-assessment.md
    - Concept Enumeration: learning-graph/list-concepts.md
    - Graph Quality Analysis: learning-graph/graph-quality-analysis.md
    - Concept Taxonomy: learning-graph/concept-taxonomy.md
    - Taxonomy Distribution Report: learning-graph/taxonomy-distribution-report.md
```

## Step 0: Setup

Tell the user that they are running the version graph generator and the version number above.

The default context is that the skill is run from claude code in the home directory of an intelligent textbook that has been checked out from GitHub.
There should be a docs directory with a standard mkdocs.yml file in the home git directory.
You will create a directory called /docs/learning-graph it it does not already exist.  
The path is relative to the git home directory.  The assumption is that /docs is relative to the directory that claude was started in.

`mkdir -p docs/learning-graph; cd docs/learning-graph`

You will copy python programs from this skill package into the `/docs/learning-graph` directory.  
You will execute python from that directory.

If you do not see the `docs` directory and the `mkdocs.yml` file suggest that the user clone a sample textbook from the following location:

`git clone https://github.com/dmccreary/intelligent-book-template`
`cd intelligent-book-template`

## Step 1: Course Description Quality Assessment

Before you begin this step, verify that it has not already been done.
To do this, check the yml metadata in the `docs/course-description.md` file.

Here is a sample of the yml metadata:

```markdown
---
title: Course Description
description: A detailed course description 
quality_score: 95
---
# Course Description
```

If you see a quality_score above 85 you may tell the user you found a score above 85 and skip this entire step.  Tell them this is a way to save tokens.

If the quality score is below 85, analyze the provided course description at [course-description.md](../course-description.md) to ensure it has enough content to generate at a minimum of 200 high-quality concepts:

1. Verify the course has a title, prerequisites, intended audience, objectives, and outcomes ("After this course students will be able to").  If these fields are missing ask the user for this information. 
1. Examine the depth and breadth of topics covered
2. Assess whether the material has sufficient granularity for at a minimum of 200 distinct concepts
3. Check for diverse topic areas and learning objectives
4. Provide detailed feedback to the user about:
   - List the expected content that you found
   - Estimated number of concepts you can derive
   - Compare this concept number with similar courses
   - Describe areas where the course description is strong
   - Any gaps or areas that might be under-represented
   - Suggest how the 2001 Bloom taxonomy (remember, understand, apply, analyze, evaluate, create) could improve the outcomes descriptions
   - Objective overall quality assessment on a scale of (1-poor to 100-perfect)
   - Suggest that the user does not proceed unless a quality score is 70 or above

Use the following rubric for creating a quality score:

### 2.2 Course Description Quality Scoring System

Evaluate the course description using this 100-point scoring system:

| Element | Points | Criteria |
|---------|--------|----------|
| **Title** | 5 | Clear, descriptive course title present |
| **Target Audience** | 5 | Specific audience identified (e.g., "college undergraduate") |
| **Prerequisites** | 5 | Prerequisites listed or explicitly stated as "None" |
| **Main Topics Covered** | 10 | Comprehensive list of topics (ideally 5-10 topics) |
| **Topics Excluded** | 5 | Clear boundaries set for what's NOT covered |
| **Learning Outcomes Header** | 5 | Clear statement: "After this course, students will be able to..." |
| **Remember Level** | 10 | Multiple specific outcomes for remembering/recalling |
| **Understand Level** | 10 | Multiple specific outcomes for understanding/explaining |
| **Apply Level** | 10 | Multiple specific outcomes for applying/using |
| **Analyze Level** | 10 | Multiple specific outcomes for analyzing/breaking down |
| **Evaluate Level** | 10 | Multiple specific outcomes for evaluating/judging |
| **Create Level** | 10 | Multiple specific outcomes for creating/synthesizing; includes capstone ideas |
| **Descriptive Context** | 5 | Additional context about course importance, relevance, or value |

**Scoring Guidelines:**
- Award full points if element is complete and high-quality
- Award partial points if element is present but incomplete or vague
- Award 0 points if element is missing
- For Bloom's Taxonomy levels, require at least 3 specific, actionable outcomes for full points

Tell user what their score was and suggest they improve the course description until the score goes above 80.

Save this report to [course-description-assessment.md](./course-description-assessment.md)

5. **Ask the user if you should proceed** with generating the learning graph

## Step 2: Generate Concept Labels

Once the course-description has been approved, generate the concept labels from the course content:

**Requirements:**
- Each Concept label must be in Title Case
- Maximum length: 32 characters
- Labels should be clear, specific, and pedagogically sound
- Cover the full breadth of the course material
- Concept Labels are entity names, not questions
- Do not use questions in the Concept Label.  Don't use "What is Git", just use "Git"

**Number of Concepts:**

For simple books, a list of 200 concepts is fine.
For complex technical books, you may generate up to 500 concepts.
Do not exceed 500 concepts unless you have good reason and the user approves this decision.
Remember that generating concept dependencies gets complex the more concepts there are.

!!! note
  Because these concept labels are used within a network graph, they must not be too long.
  Otherwise the graph will be hard to read.

**Output:**
- Save the numbered list to [concept-list.md](./concept-list.md)
- Format: Simple numbered list (1-500) in a markdown file
- Make sure that each number is unique so it can be used as a ConceptID
- Inform the user the file has been created
- Tell the user they should view the list and add and remove concepts now
- Tell the user it is best review the concept list before the next steps

Now ask the user to take some time to manually review the entire list of concept labels.
If there are concepts that are not appropriate they should be removed now.
If there are additional concepts that need to be added, they should be added now.
It will require a lot of extra tokens later to change the content later.
This is an important review step to ensure the quality of the textbook.
Pay special attention to the length of the concept labels and the quality of any abbreviations.

## Step 3: