plasma-expert/phases/phase-01-restructuring.md

Phase 01: Project Restructuring

Date: 2026-02-10 Status: Complete

What Changed

Restructured the project from a linear educational course (30 lessons, 18 exercises, PyQt app skeleton) into an evolving research knowledge base.

Motivation

The original structure was built to support a Khan Academy-style desktop application. While the physics content was research-grade (91/100 quality assessment), the course format imposed:

• Fixed linear progression - concepts locked into lesson sequence
• Pedagogical overhead - difficulty levels, time estimates, grading tolerances, learning paths
• App coupling - content structured around a PyQt viewer that was never completed
• Monolithic planning - a single massive CLAUDE.md documenting every development decision

What we actually need is a living research system - a knowledge graph where concepts link to each other, open questions are tracked, and new findings can be integrated without restructuring an entire curriculum.

What Was Done

1. Archived all course scaffolding into _archive/course/:

   • 30 lesson markdown files (4 parts, ~10,000 lines)
   • 18 YAML exercise files (525 assessment points)
   • course.json navigation structure
   • PyQt app skeleton (15+ Python files)
   • Learning paths, difficulty metadata, time estimates

2. Created context/ with ~15 coarse topic files:

   • Each is a self-contained research document on one conceptual area
   • YAML frontmatter with relationship metadata and cross-references
   • [[wiki-link]] syntax for inline navigation
   • status field (established / provisional / speculative)
   • source_sections tracing back to spark-physics.txt

3. Preserved all research content:

   • spark-physics.txt unchanged at root (source of truth)
   • 5 worked examples moved to examples/
   • 22 matplotlib images + 15 placeholders moved to assets/
   • Glossary (64 terms) updated to reference topic IDs
   • Equations and physical bounds consolidated into context/equations-and-bounds.md

4. Reorganized utilities:

   • Image generation scripts moved to tools/
   • One-time migration script in tools/update_glossary.py

Content Mapping

Previous (Course)	New (Knowledge Graph)
lessons/01-fundamentals/01-introduction.md thru 06	context/circuit-topology.md
lessons/02-optimization/01-02	context/power-optimization.md
lessons/02-optimization/03-05	context/thevenin-method.md
lessons/02-optimization/06	context/coupled-resonance.md
lessons/03-spark-physics/01	context/field-thresholds.md
lessons/03-spark-physics/02-04	context/energy-and-growth.md
lessons/03-spark-physics/05	context/thermal-physics.md
lessons/03-spark-physics/06	context/streamers-and-leaders.md
lessons/03-spark-physics/07	context/capacitive-divider.md
lessons/03-spark-physics/08	context/empirical-scaling.md
lessons/04-advanced-modeling/01-02	context/lumped-model.md
lessons/04-advanced-modeling/03-05	context/distributed-model.md
lessons/04-advanced-modeling/02,04	context/femm-workflow.md
reference/equation-sheet.md + physical-bounds.md	context/equations-and-bounds.md
(scattered across lessons)	context/open-questions.md

What Was NOT Changed

• spark-physics.txt - untouched, remains source of truth
• Physics content accuracy - all formulas and derivations preserved
• Sign conventions - Maxwell matrix conventions preserved
• Peak value convention - all phasors still use peak values

Metrics

Metric	Before	After
Content files	30 lessons + 18 exercises	~15 topic files
Navigation	course.json (fixed tree)	Cross-references (graph)
Entry point	Lesson 1	Any topic file
Adding content	Create lesson, update course.json, add exercise	Edit topic file or create new one
Reference lookup	Separate equation-sheet.md	Inline in topic + combined reference
Open questions	Buried in Part 12	Dedicated topic file + per-concept tracking

Next Steps

• Expand topic files as research evolves
• Split topics when they exceed ~25k tokens
• Build expert agent backed by spark-physics.txt
• Add new research phases as investigations proceed