faq-generator

What this skill does

# FAQ Generator

Generate comprehensive, categorized FAQs from textbook content and chatbot-ready JSON exports.  Place the
FAQs into the file docs/faq.md.  Log the results of the session to `logs/faq.md`.

## Purpose

This skill automates FAQ creation for intelligent textbooks by analyzing course content, learning graphs, and glossary terms to generate relevant questions and answers. The skill organizes questions by category and difficulty, ensures Bloom's Taxonomy distribution across cognitive levels, provides answers with links to source content, and exports structured JSON data ready for RAG system integration.

## When to Use This Skill

Use this skill after the following artifacts exist:

1. Course description has been finalized with a quality score above 70
2. Learning graph has been created
3. Glossary has been generated
4. At least 30% of chapter content has been written

Having these prerequisites ensures the FAQ generator has sufficient context to create meaningful, relevant questions. Trigger this skill when:

- Building initial FAQ for a new textbook
- Updating FAQ after significant content additions
- Preparing content for chatbot or AI assistant integration
- Identifying knowledge gaps in existing content

## Markdown Formatting

1. Use markdown header level one (#) for the FAQ title
2. Use markdown header level two (##) for each category
3. Use markdown header level three (###) for each individual question
4. Place the answer in the body text

Use the faq-template.md in the skill references section as your template.

## Critical Rule: No Anchor Links

!!! warning "NEVER Use Anchor Links"
    **All links must point to files only, never with `#` anchor fragments.**

    Anchor links (`file.md#section-name`) break frequently because:

    - Section headers change during content editing
    - Anchors are case-sensitive and whitespace-sensitive
    - MkDocs anchor auto-generation is unpredictable
    - Broken anchors cause build warnings and confuse users

    ✅ **Correct:** `[See Ohm's Law](chapters/02-ohms-law/index.md)`

    ❌ **Wrong:** `[See Ohm's Law](chapters/02-ohms-law/index.md#series-circuits)`

## Workflow

### Step 1: Assess Content Completeness

Calculate a content completeness score (1-100 scale) to determine FAQ generation feasibility:

**Required Inputs:**

1. Read `docs/course-description.md`
   - Check for: title, audience, prerequisites, learning outcomes
   - Verify Bloom's Taxonomy outcomes present
   - Score: 25 points if complete

2. Read `docs/learning-graph/03-concept-dependencies.csv`
   - Validate DAG structure (no cycles)
   - Count concepts and dependencies
   - Score: 25 points if valid DAG with good connectivity

3. Read `docs/glossary.md`
   - Count terms (50+ = good, 100+ = excellent)
   - Score: 15 points for 100+, 10 for 50-99, 5 for <50

4. Scan all `docs/**/*.md` files
   - Calculate total word count
   - Target: 10,000+ words for comprehensive FAQ
   - Score: 20 points for 10k+, 15 for 5k-10k, 10 for <5k

5. Calculate concept coverage
   - What % of learning graph concepts have related chapter content?
   - Score: 15 points for 80%+, 10 for 60-79%, 5 for <60%

**Content Completeness Score Ranges:**

- 90-100: All inputs present with high quality
- 70-89: Core inputs present, some content gaps
- 50-69: Missing optional inputs or low word count
- Below 50: Critical inputs missing

**User Dialog Triggers:**

- Score < 60: Ask "Limited content available for FAQ generation. Continue with basic FAQ or wait for more content?"
- No glossary: Ask "No glossary found. Generate FAQ anyway (limited technical questions) or create glossary first?"
- Low word count: Ask "Only [N] words of content found. FAQ quality may be limited. Proceed?"

If user agrees to proceed with score < 60, generate FAQ but include disclaimer in quality report about limited content.

### Step 2: Analyze Content for Question Opportunities

Read and analyze all content sources to identify common question patterns:

**From Course Description:**

- "What is this course about?" (scope)
- "Who is this course for?" (audience)
- "What will I learn?" (outcomes)
- "What do I need to know first?" (prerequisites)

**From Learning Graph:**

- "What is [concept]?" (definition questions)
- "How does [concept A] relate to [concept B]?" (relationship questions)
- "What do I need to know before learning [concept]?" (prerequisite questions)
- "What comes after [concept]?" (progression questions)

**From Glossary:**

- "What does [term] mean?" (terminology questions)
- "What's the difference between [term A] and [term B]?" (comparison questions)
- "Can you give an example of [term]?" (application questions)

**From Chapter Content:**

- Identify recurring themes or topics
- Note areas where students might struggle (complex concepts)
- Extract common misconceptions if mentioned
- Find practical application examples

**From Existing FAQ (if present):**

- Read `docs/faq.md` if it exists
- Preserve manually curated questions
- Merge with new generated questions
- Remove duplicates, keeping manual version when conflict

### Step 3: Generate Question Categories

Create 6 standard categories aligned with learning progression:

**1. Getting Started Questions (10-15 questions)**

Target Bloom's levels: 60% Remember, 40% Understand

- Course overview and objectives
- Prerequisites and preparation
- How to use the textbook
- Navigation and structure
- Time commitment and difficulty

**2. Core Concept Questions (20-30 questions)**

Target Bloom's levels: 20% Remember, 40% Understand, 30% Apply, 10% Analyze

- Key concepts from learning graph (prioritize high-centrality nodes)
- Fundamental principles
- Concept relationships and dependencies
- How concepts build on each other

**3. Technical Detail Questions (15-25 questions)**

Target Bloom's levels: 30% Remember, 40% Understand, 20% Apply, 10% Analyze

- Terminology from glossary
- Definitions and explanations
- Technical comparisons
- Specification details

**4. Common Challenges (10-15 questions)**

Target Bloom's levels: 10% Remember, 30% Understand, 40% Apply, 20% Analyze

- Difficult concepts requiring extra explanation
- Common misconceptions
- Troubleshooting scenarios
- Error resolution

**5. Best Practice Questions (10-15 questions)**

Target Bloom's levels: 10% Understand, 40% Apply, 30% Analyze, 15% Evaluate, 5% Create

- How to apply concepts effectively
- Recommended approaches
- When to use specific techniques
- Real-world applications

**6. Advanced Topics (5-10 questions)**

Target Bloom's levels: 10% Apply, 30% Analyze, 30% Evaluate, 30% Create

- Complex integrations
- Edge cases
- Performance optimization
- Future directions

### Step 4: Generate Questions and Answers

For each category, generate questions following these guidelines:

**Question Format:**

- Use level-2 headers (##)
- Write as actual questions (end with ?)
- Make questions specific and searchable
- Use terminology from glossary
- Keep questions concise (5-15 words)

**Answer Format:**

- Use a level 3 markdown header (###) for each question
- Write complete, standalone answers
- Include examples for 40% of answers
- Link to relevant sections (target: 60%+ linked)
- Target length: 100-300 words
- Use clear, direct language
- Address the question fully

**Bloom's Taxonomy Guidelines:**

**Remember:** Recall facts, terms, basic concepts

- "What is [concept]?"
- "What does [term] mean?"
- "What are the components of [system]?"

**Understand:** Explain ideas or concepts

- "How does [concept] work?"
- "Why is [concept] important?"
- "What is the difference between [A] and [B]?"

**Apply:** Use information in new situations

- "How do I [perform task]?"
- "When should I use [technique]?"
- "What's an example of [concept] in practice?"

**Analyze:** Draw connections among ideas

- "What is the relationship between [A] and [B]?"
- "How does [concept] relate to [other concept]?"
- "What are the underlying causes of [issue]?"

**Evaluate:** J