Quest Quality Checklist - Quick Reference¶

Use this checklist when creating or updating quests to ensure high quality

✅ Required Frontmatter (17 points)¶

Basic Information¶

title - Clear, action-oriented (< 60 chars for SEO)
description - Complete description (150-300 chars)
date - ISO 8601 format (YYYY-MM-DDTHH:MM:SS.000Z)
preview - Image path
author - Quest creator name
layout - Should be "journals"
permalink - Start with /quests/level-XXXX-name/
fmContentType - Should be "quest"

Quest Classification¶

level - 4-digit binary (0000-1111)
difficulty - One of: 🟢 Easy, 🟡 Medium, 🔴 Hard, ⚔️ Epic
estimated_time - Format: "XX-XX minutes" or "X-X hours"
primary_technology - Main tech focus
quest_type - E.g., tool-mastery, language-learning
skill_focus - E.g., frontend, backend, testing
learning_style - E.g., hands-on, conceptual
quest_series - Series name or "Standalone Quest"

Metadata¶

tags - Include level tag (lvl-XXXX) + relevant tags
categories - [Quests, Tech-Category, Skill-Level]
keywords - primary and secondary keywords

🌟 Enhanced Fields (8 points)¶

quest_line - Campaign/storyline name
quest_arc - Story arc or thematic grouping
prerequisites - Knowledge, system, skill requirements
quest_dependencies - Recommended/unlocked quests
quest_relationships - Parent/child/parallel/sequel quests
learning_paths - Primary paths and character classes
rewards - Badges, skills, progression points
validation_criteria - Completion requirements

📝 Content Structure (9 points)¶

Opening - Fantasy-themed introduction
Legend - Explain why this quest matters
🎯 Quest Objectives - Clear learning outcomes
🗺️ Prerequisites - Required knowledge and systems
🌍 Platform Instructions - macOS, Windows, Linux paths
Chapters - Progressive learning sections
🎮 Challenges - Implementation exercises
✅ Completion Verification - Achievement checklist
🏆 Rewards - Next steps and resources

💻 Code Quality (5 points)¶

All code blocks have language specification
```
# Good - has "python" specification
```

# Bad - no language specification

✨ Interactivity (5 points)¶

Interactive checkboxes throughout
Knowledge checks after chapters
Progress tracking elements
Engagement prompts

Examples: - [ ] Can you explain this concept? - [ ] What would happen if...? - [ ] Try implementing...

🧙‍♂️ Fantasy Theme (10 points)¶

Use gamification language throughout: - ⚔️ Skills, spells, quests, adventures - 🏰 Towers, realms, kingdoms, territories - 🧙‍♂️ Wizards, masters, heroes, champions - 🏆 Badges, achievements, rewards - ✨ Magic, enchantments, powers - 🗺️ Paths, journeys, expeditions

Fantasy element checklist: - [ ] Opening uses adventure language - [ ] Objectives framed as quest goals - [ ] Chapter titles use fantasy themes - [ ] Rewards described as achievements - [ ] Consistent emoji usage - [ ] Engaging narrative voice

📱 Accessibility (3 points)¶

All images have descriptive alt text
Clear heading hierarchy
Descriptive link text (not "click here")
Inclusive language throughout
Multi-platform support

📚 Citations (5 points)¶

References section included
Official documentation linked
Academic sources cited
Tutorial resources provided

Example structure:

### 📚 Further Study and Resources

**Official Documentation**:
- [Tool Documentation](https://example.com/docs)

**Academic Resources**:
- [University Course](https://example.edu/course)

**Tutorials**:
- [Community Guide](https://example.com/guide)

🎯 Target Scores¶

Minimum Passing: 70% (52.5 / 75 points)
Good Quality: 80% (60 / 75 points)
Excellent Quality: 90% (67.5 / 75 points)
Perfect Quest: 100% (75 / 75 points)

🚀 Quick Validation Commands¶

# Validate your quest (from project root)
docker-compose run --rm quest-validator \
    /opt/venv/bin/python /app/test/quest-validator/quest_validator.py \
    /app/pages/_quests/your-quest.md

# Verbose output for details
docker-compose run --rm quest-validator \
    /opt/venv/bin/python /app/test/quest-validator/quest_validator.py \
    /app/pages/_quests/your-quest.md -v

# Generate report
docker-compose run --rm quest-validator \
    /opt/venv/bin/python /app/test/quest-validator/quest_validator.py \
    /app/pages/_quests/your-quest.md \
    --report /app/test/quest-validator/report.json

# Run full test suite
./test/quest-validator/test-validator.sh

🔧 Common Issues & Fixes¶

Issue: Low Code Quality Score¶

Fix: Add language specifications to all code blocks

```python  ← Add this
def example():
    pass
\```

Issue: Missing Enhanced Fields¶

Fix: Add quest hierarchy to frontmatter

quest_line: "Your Campaign Name" quest_arc: "Story Arc" quest_dependencies:
    recommended_quests:
        - "Prerequisite Quest"

Issue: Low Fantasy Theme Score¶

Fix: Use more gamification language - Change "Learn" → "Master" or "Forge" - Change "Tutorial" → "Quest" or "Adventure" - Change "Complete" → "Conquer" or "Achieve" - Add emoji indicators (🎯⚔️🏆✨)

Issue: No Interactive Elements¶

Fix: Add checkboxes throughout

- [ ] Can you explain the concept?
- [ ] Have you tested your code?
- [ ] Did you document your work?

📋 Pre-Submission Checklist¶

Before submitting your quest:

🎓 Quality Philosophy¶

Remember: High-quality quests create better learning experiences!

✨ Engage - Use fantasy themes and interactivity
📚 Educate - Provide clear, progressive learning
🌍 Include - Support all platforms and skill levels
🎯 Validate - Ensure measurable outcomes
🔗 Connect - Link to broader learning paths

For detailed documentation, see: Quest Validator README

Happy Quest Crafting! 🧙‍♂️✨