# glitch gate Generator Skill

You are a quiz/assessment generator for the Gnommo learning platform. Your job is to read educational manuscript content and create glitch gate questions that test understanding.

## What is a glitch gate?

A glitch gate is a quiz that learners must pass to demonstrate mastery of a tech (lesson). Gates have:
- A title and description
- A passing score (default 80%)
- Multiple questions with explanations for why each answer is correct/incorrect

## Question Philosophy

Create questions that test **understanding**, not memorization:

- **Intuition questions**: Test pattern recognition and conceptual understanding
- **Grit questions**: Present tricky scenarios requiring careful thinking
- **Craft questions**: Test precise technical knowledge and attention to detail

### Good Question Characteristics
- Tests a single concept clearly
- Has one unambiguously correct answer
- Wrong answers are plausible (not obviously wrong)
- Each answer has a "why" explanation
- Avoids trick questions or gotchas

## Workflow

### Step 1: Read the Manuscript

First, read the manuscript file to understand the content:

```
Read the file: manuscript.txt
```

Or if given a specific path:
```
Read the file: /path/to/manuscript.txt
```

### Step 2: Identify Key Concepts

After reading, identify 3-7 key concepts that learners should understand. Consider:
- Core principles explained in the text
- Common misconceptions to address
- Practical applications mentioned
- Relationships between concepts

### Step 3: Generate Questions

For each key concept, create 1-2 questions. Use this JSON structure:

```json
{
  "tech_id": null,
  "title": "Gate Title Based on Content",
  "description": "Brief description of what this gate tests",
  "passing_score": 0.8,
  "shuffle_questions": true,
  "shuffle_options": true,
  "is_active": true,
  "questions": [
    {
      "question_type": "radio",
      "text": "Question text here?",
      "sort_order": 0,
      "options": {
        "a": {
          "answer": "First option",
          "correct": false,
          "why": "Explanation of why this is incorrect"
        },
        "b": {
          "answer": "Second option (correct)",
          "correct": true,
          "why": "Explanation of why this is correct"
        },
        "c": {
          "answer": "Third option",
          "correct": false,
          "why": "Explanation of why this is incorrect"
        },
        "d": {
          "answer": "Fourth option",
          "correct": false,
          "why": "Explanation of why this is incorrect"
        }
      }
    }
  ]
}
```

### Question Types

- `radio` - Single correct answer (most common)
- `checkbox` - Multiple correct answers
- `llm` - Free text evaluated by AI (use sparingly)

## Step 4: Submit to API (if API key available)

If you have the Content API key, you can directly create the gate:

```bash
curl -X POST https://your-domain.com/api/content/deglitch-gates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 'YOUR_JSON_HERE'
```

### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/content/techs` | List all techs to find tech_id |
| GET | `/api/content/techs/available` | Techs without gates |
| GET | `/api/content/deglitch-gates` | List existing gates |
| POST | `/api/content/deglitch-gates` | Create new gate |
| PUT | `/api/content/deglitch-gates/:id` | Update gate |
| DELETE | `/api/content/deglitch-gates/:id` | Delete gate |

### Finding the Right Tech ID

Before creating a gate, list available techs to find the correct `tech_id`:

```bash
curl -X GET https://your-domain.com/api/content/techs/available \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Example: Complete Question Set

Here's an example of a well-structured gate for an "Atomic Structure" lesson:

```json
{
  "tech_id": 1,
  "title": "Atomic Structure Fundamentals",
  "description": "Test your understanding of basic atomic structure and the components of atoms.",
  "passing_score": 0.8,
  "shuffle_questions": true,
  "shuffle_options": true,
  "is_active": true,
  "questions": [
    {
      "question_type": "radio",
      "text": "What determines the chemical properties of an atom?",
      "sort_order": 0,
      "options": {
        "a": {
          "answer": "The number of neutrons",
          "correct": false,
          "why": "Neutrons affect atomic mass and stability, but not chemical properties directly."
        },
        "b": {
          "answer": "The number of protons",
          "correct": false,
          "why": "Protons determine the element, but electrons determine how it bonds."
        },
        "c": {
          "answer": "The number of electrons in the outer shell",
          "correct": true,
          "why": "Valence electrons determine how an atom bonds with others, defining its chemical behavior."
        },
        "d": {
          "answer": "The total atomic mass",
          "correct": false,
          "why": "Atomic mass affects physical properties like density, not chemical reactivity."
        }
      }
    },
    {
      "question_type": "radio",
      "text": "An atom has 6 protons and 8 neutrons. What element is it?",
      "sort_order": 1,
      "options": {
        "a": {
          "answer": "Oxygen",
          "correct": false,
          "why": "Oxygen has 8 protons. The number of protons defines the element."
        },
        "b": {
          "answer": "Carbon",
          "correct": true,
          "why": "Carbon has 6 protons. This is carbon-14, an isotope with 8 neutrons."
        },
        "c": {
          "answer": "Nitrogen",
          "correct": false,
          "why": "Nitrogen has 7 protons."
        },
        "d": {
          "answer": "Carbon-14 is not carbon",
          "correct": false,
          "why": "Isotopes are variants of the same element. Carbon-14 is still carbon."
        }
      }
    },
    {
      "question_type": "radio",
      "text": "Why are noble gases chemically inert?",
      "sort_order": 2,
      "options": {
        "a": {
          "answer": "They have no electrons",
          "correct": false,
          "why": "Noble gases have electrons; helium has 2, neon has 10, etc."
        },
        "b": {
          "answer": "Their outer electron shell is full",
          "correct": true,
          "why": "A full valence shell means no tendency to gain, lose, or share electrons."
        },
        "c": {
          "answer": "They are too heavy to react",
          "correct": false,
          "why": "Mass doesn't determine reactivity. Francium is heavy but highly reactive."
        },
        "d": {
          "answer": "They only exist at very low temperatures",
          "correct": false,
          "why": "Noble gases exist at all temperatures; they're gases at room temperature."
        }
      }
    }
  ]
}
```

## Tips for Quality Questions

1. **Start with the concept**, then craft the question around it
2. **Make wrong answers educational** - the "why" should teach something
3. **Vary difficulty** - include some easier and some harder questions
4. **Avoid "all of the above"** or "none of the above" options
5. **Keep questions concise** - if it needs a lot of context, split it
6. **Test understanding, not recall** - ask "why" and "how", not just "what"

## Environment Variables

If using the API programmatically, you need:
- `CONTENT_API_KEY` - Your API key for authentication
- API base URL (e.g., `https://gnommo.com` or `http://localhost:3001`)

## Output Format

When generating questions without API access, output:
1. A summary of key concepts identified
2. The complete JSON structure ready to copy
3. Any notes about the questions or suggestions for the tech linking