documentation-generation

# Epic XX: Epic Name

**Status:** Planning/Active/Complete
**Created:** YYYY-MM-DD
**Parent:** [Link to parent epic or exploration document]

---

## Executive Summary

Brief (2-3 sentences) description of what this epic accomplishes and why it matters.

**Core insight**: Key technical insight that drives the epic approach.

---

## Scope

### What's IN

| Phase | Feature | Priority | Document |
|-------|---------|----------|
| **1** | Feature A description | P0 - Critical | [PHASE1_FEATURE_A.md](./PHASE1_FEATURE_A.md) |
| **2** | Feature B description | P1 - Important | [PHASE2_FEATURE_B.md](./PHASE2_FEATURE_B.md) |
| **3** | Feature C description | P2 - Nice to have | [PHASE3_FEATURE_C.md](./PHASE3_FEATURE_C.md) |

### What's OUT (Post-MVP)

- Feature D - Reason for exclusion
- Feature E - Technical complexity
- Feature F - Timeline constraints

---

## Technical Decisions Summary

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Architecture pattern | Choice | Why this approach |
| Technology stack | Choice | Benefits and tradeoffs |
| Data model | Choice | Scalability considerations |

---

## Success Metrics

| Metric | Target | How to Measure |
|--------|--------|-----------------|
| User adoption | X users | Telemetry: `feature_used` |
| Performance | <3s load time | Performance monitoring |
| Error rate | <1% | Error tracking |
| Test coverage | >90% | Coverage reports |

---

## Timeline Philosophy

- No time estimates provided. Work in phases:
  1. Complete Phase 1, ship, measure
  2. If successful, proceed to Phase 2
  3. If successful, proceed to Phase 3

Each phase is independently valuable. Stop if metrics don't justify continuation.

---

## Development Standards

### Testing Requirements

| Requirement | Phase 1 | Phase 2 | Phase 3 |
|-------------|---------|---------|---------|
| Unit tests | ✅ | ✅ | ✅ |
| E2E tests | ✅ | ✅ | ✅ |
| Performance tests | - | ✅ | ✅ |
| Security tests | - | - | ✅ |

### Code Quality Requirements

| Requirement | Target |
|-------------|--------|
| Architecture compliance | Zero violations |
| Type checking | No errors |
| Test coverage | >90% |
| Bundle size | <5MB |

### Documentation Requirements

| Requirement | Frequency |
|-------------|----------|
| Learning notes | After each session |
| Phase documentation | At phase completion |
| Epic updates | Major milestones |
| API updates | Public API changes |

---

## Risk Management

| Risk | Probability | Impact | Mitigation |
|------|-------------|---------|------------|
| Technical complexity | Medium | Timeline | Proof of concept first |
| User adoption | Low | Success | Beta testing with feedback |
| Performance | Low | Experience | Performance monitoring |
| Security | Low | Data | Security audit |

---

## Related Documentation

- [Parent Exploration](./EXPLORATION.md)
- [Architecture Overview](../../../architecture/README.md)
- [API Reference](../../../api/README.md)
- [Previous Epic](../epicXX_PREVIOUS/EPIC_XX_PLAN.md)

---

**Last Updated:** YYYY-MM-DD
**Next Review:** YYYY-MM-DD

# Phase X: Phase Name

**Status:** Ready/In Progress/Complete
**Priority:** High/Medium/Low (Area)
**Estimated Effort:** X-Y sessions
**Created:** YYYY-MM-DD
**Updated:** YYYY-MM-DD

---

## Session Log

| Date | Status | Notes |
|------|--------|-------|
| YYYY-MM-DD | **Started** | Initial planning and setup |
| YYYY-MM-DD | **Progress** | Implemented core functionality |
| YYYY-MM-DD | **Complete** | Testing and documentation |

---

## Overview

Brief description of what this phase accomplishes and how it fits into the epic.

**Key Goal:** What success looks like for this phase.

---

## What You'll Learn

### New Technologies & Concepts

1. **Technology Name** - Brief description and why important
2. **Pattern Name** - Development pattern and benefits
3. **Tool Name** - New tool and learning objectives

---

## Prerequisites

Before starting this phase, you should have:

- ✅ **Previous Phase Complete** - What was delivered
- ✅ Required tools installed - Development environment
- ✅ Knowledge of dependencies - APIs, libraries
- ✅ Understanding of patterns - Established approaches

---

## Branching Strategy

### Branch Naming

### Workflow
1. Create branch from `main`
2. Make small, focused commits
3. Push regularly to remote
4. Create PR when phase complete
5. Merge to `main` after review

### Commands
```bash
# Start phase
git checkout main
git pull origin main
git checkout -b feature/phaseX-phase-name

# During work
git add <files>
git commit -m "type(scope): description"

# Push regularly
git push -u origin feature/phaseX-phase-name

# When complete
gh pr create --title "Phase X: Phase Name" --body "..."

## Learning Notes Generation

### Step 1: Session Learning Notes Template

**File:** `docs/learning/epicXX_epic-name/PHASE*_LEARNING_NOTES.md`

```markdown
# Phase X: Session Learning Notes

**Date:** YYYY-MM-DD
**Type:** [development|testing|debugging|planning]
**Session:** X of Y
**Duration:** Z hours
**Participants:** [List if pair programming]

---

## Session Objective

What was planned to accomplish in this session.

---

## What Was Accomplished

### Completed Tasks
- [ ] Task 1 description
- [ ] Task 2 description
- [ ] Task 3 description

### Code Changes
- **Files Modified:** [List of files]
- **Lines Added:** [Number]
- **Lines Removed:** [Number]
- **Tests Added:** [Number]

---

## Problems Encountered

### Technical Issues
1. **Problem:** Clear description
   **Solution:** How it was resolved
   **Time Lost:** Estimate of time spent
   **Learning:** What to avoid in future

### Process Issues
1. **Problem:** Development process issue
   **Solution:** Process improvement
   **Root Cause:** Why it happened
   **Prevention:** How to prevent recurrence

---

## Key Learnings

### Technical Learnings
1. **Pattern Discovered:** New development pattern
   **Application:** Where and how to use it
   **Benefits:** Why this is valuable

2. **Tool Mastery:** New tool or feature
   **Usage:** How it was used effectively
   **Tips:** Best practices discovered

### Process Learnings
1. **Workflow Improvement:** Better way to work
   **Old Way:** Previous approach
   **New Way:** Improved approach
   **Efficiency Gain:** Time or effort saved

---

## Metrics and Results

### Performance Metrics
| Metric | Before | After | Improvement |
|--------|--------|--------|-------------|
| Test coverage | X% | Y% | +Z% |
| Build time | Xs | Ys | -Zs |
| Bundle size | Xkb | Ykb | +/-Zkb |

### Quality Metrics
| Metric | Before | After | Status |
|--------|--------|--------|-------|
| Architecture violations | X | Y | ✅ Improved |
| TypeScript errors | X | Y | ✅ Fixed |
| Linting issues | X | Y | ✅ Reduced |

---

## Next Steps

### Immediate (Next Session)
1. [ ] Task to continue
2. [ ] Issue to investigate
3. [ ] Test to write

### Upcoming (This Phase)
1. [ ] Remaining implementation tasks
2. [ ] Documentation to complete
3. [ ] Testing to perform

### Future (Next Phases)
1. [ ] Knowledge to apply to phase X+1
2. [ ] Process improvements to implement
3. [ ] Tools to master

---

## Screenshots and Evidence

[Attach screenshots of progress, test results, or important milestones]

---

## Session Reflection

### What Went Well
- Clear description of successful aspects
- Why it worked well
- How to replicate success

### What Could Be Improved
- Areas for improvement
- Specific suggestions
- Action items for improvement

### Unexpected Discoveries
- Surprising findings
- New opportunities identified
- Risks or concerns discovered

---

## Process Documentation Updates

### Templates Updated
- [ ] Phase template with new learnings
- [ ] Checklists with additional items
- [ ] Time estimates refined

### Cross-References Added
- [ ] Links to related documentation
- [ ] Updated architecture diagrams
- [ ] Added to project knowledge base

---

**Session Summary:**
**Duration:** X hours
**Tasks Completed:** Y of Z planned
**Progress:** Phase X is [percentage]% complete
**Next Session:** Focus on [priority items]

---

**Last Updated:** YYYY-MM-DD

{
  "source": {
    "include": ["src/**/*.js"],
    "exclude": ["src/**/*.test.js", "src/version.js"],
    "includePattern": ".+\\.js(doc)?$"
  },
  "opts": {
    "destination": "./docs/api/",
    "recurse": true
  },
  "plugins": [
    "plugins/markdown",
    "plugins/summarize"
  ],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false,
    "default": {
      "outputSourceFiles": true,
      "includeDate": true
    }
  },
  "markdown": {
    "parser": "gfm",
    "hardwrap": true,
    "idInHeadings": true
  }
}

# Saberloop API Documentation

## Overview

This document describes the internal API used by Saberloop views, services, and components.

## Architecture

The API is organized into logical modules:

| Module | Purpose | Key Functions |
|--------|---------|---------------|
| Core | State management and database | `initDatabase()`, `state` |
| Services | Business logic layer | `quizService`, `partyService` |
| API | External communication | `generateQuiz()`, `saveQuiz()` |
| Utils | Helper functions | `shuffle()`, `formatScore()` |

## Module Documentation

### Core Module (`src/core/`)

#### Database (`db.js`)
```javascript
/**
 * Initialize the IndexedDB database and create object stores
 * @returns {Promise<IDBDatabase>} Database instance
 */
export async function initDatabase() {
  // Implementation
}

/**
 * Save a quiz to the database
 * @param {Quiz} quiz - Quiz object to save
 * @returns {Promise<string>} Quiz ID
 */
export async function saveQuiz(quiz) {
  // Implementation
}

/**
 * Get current value from global state
 * @param {string} key - State key to retrieve
 * @returns {any} Current value
 */
export function get(key) {
  // Implementation
}

/**
 * Subscribe to state changes
 * @param {Function} callback - Callback function
 * @returns {Function} Unsubscribe function
 */
export function subscribe(callback) {
  // Implementation
}

/**
 * Create a new quiz with AI-generated questions
 * @param {string} topic - Quiz topic
 * @param {Object} options - Quiz options
 * @returns {Promise<Quiz>} Generated quiz
 */
export async function createQuiz(topic, options = {}) {
  // Implementation
}

/**
 * Validate quiz answers and calculate score
 * @param {Quiz} quiz - Quiz object
 * @param {Array} answers - User answers
 * @returns {QuizResult} Score and results
 */
export function calculateScore(quiz, answers) {
  // Implementation
}

/**
 * Generate quiz questions using AI
 * @param {string} topic - Topic for questions
 * @param {number} questionCount - Number of questions to generate
 * @param {string} language - Language for questions
 * @returns {Promise<Object>} Generated questions and metadata
 */
export async function generateQuiz(topic, questionCount, language = 'en') {
  // Implementation
}

import { quizService } from '@/services/quiz-service.js';

// Create a science quiz with 10 questions
const quiz = await quizService.createQuiz('Science', {
  questionCount: 10,
  difficulty: 'medium',
  language: 'en'
});

console.log('Quiz created:', quiz.id);

import { state, subscribe } from '@/core/state.js';

// Get current user settings
const settings = state.get('userSettings');

// Subscribe to changes
const unsubscribe = subscribe((newState) => {
  console.log('State changed:', newState);
});

// Later: stop listening
unsubscribe();

import { saveQuiz, loadQuiz } from '@/core/db.js';

// Save a quiz
await saveQuiz({
  id: 'quiz-123',
  topic: 'History',
  questions: [...]
});

// Load a quiz
const quiz = await loadQuiz('quiz-123');

try {
  const result = await apiCall(data);
  return result;
} catch (error) {
  logger.error('API call failed', { error: error.message });
  throw new Error(handleApiError(error));
}

## Automation Scripts

### Step 1: Documentation Generation Scripts

**File:** `scripts/generate-docs.cjs`

```javascript
const fs = require('fs');
const path = require('path');

/**
 * Generate API documentation from JSDoc comments
 */
function generateApiDocs() {
  console.log('📚 Generating API documentation...');
  
  const { execSync } = require('child_process');
  
  try {
    execSync('npm run docs', { stdio: 'inherit' });
    console.log('✅ API documentation generated');
  } catch (error) {
    console.error('❌ Failed to generate API docs:', error.message);
    process.exit(1);
  }
}

/**
 * Generate learning notes template
 */
function generateLearningNotes(phaseName) {
  const template = `
# Phase: ${phaseName} Learning Notes

**Date:** ${new Date().toISOString().split('T')[0]}
**Status:** In Progress

## Session Objectives
[Add objectives here]

## What Was Accomplished
[Track progress here]

## Problems Encountered
[Document issues here]

## Key Learnings
[Capture learnings here]
`;

  const filename = `docs/learning/epicXX_epic-name/PHASE*_LEARNING_NOTES.md`;
  fs.writeFileSync(filename, template);
  console.log(`✅ Learning notes template created: ${filename}`);
}

// CLI interface
const command = process.argv[2];
const phaseName = process.argv[3];

switch (command) {
  case 'api':
    generateApiDocs();
    break;
  case 'notes':
    generateLearningNotes(phaseName);
    break;
  default:
    console.log('Usage: node scripts/generate-docs.cjs [api|notes] [phase-name]');
    process.exit(1);
}

{
  "scripts": {
    "docs": "jsdoc -c jsdoc.config.json",
    "docs:open": "jsdoc -c jsdoc.config.json && start docs/api/index.html",
    "docs:generate": "node scripts/generate-docs.cjs",
    "docs:notes": "node scripts/generate-docs.cjs notes"
  }
}