feat: add comprehensive audit reports and enhancement roadmap

5 parallel research agents produced:
- Content quality audit (docs, projects, concepts, quizzes, challenges)
- Competitive analysis (13 platforms: freeCodeCamp, Exercism, py4e, etc.)
- Teaching innovations research (Pyodide, uv, type hints, AI tutoring)
- Technical infrastructure audit (CI/CD, tooling, cross-platform)
- Community & engagement strategy (growth playbook, classroom adoption)

ENHANCEMENT_ROADMAP.md synthesizes all findings into 45 prioritized
enhancements across 5 tiers, with implementation phases and a top-10
highest-ROI list.

Critical finding: 165 core-track projects share identical templated
project.py, tests, and README body sections — the single biggest
quality improvement opportunity.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: travisjneuman

ENHANCEMENT_ROADMAP.md

@@ -0,0 +1,172 @@
+# Enhancement Roadmap
+
+> Synthesized from 5 parallel research audits conducted February 2025. This document prioritizes every identified improvement by impact and effort.
+
+---
+
+## Key Findings Summary
+
+### Content Audit
+The curriculum's foundation (concept guides, quizzes, flashcards, challenges, expansion modules) is genuinely excellent. The critical issue: **165 core-track projects (levels 0-10) share identical templated `project.py`, tests, and README body sections**. A "Word Counter" has the same code as a "Dictionary Lookup Service." This is the single highest-impact fix available.
+
+### Competitive Analysis
+learn.python's 261 projects across 13 levels is more comprehensive than any free competitor. The gaps are not in content volume but in **delivery**: no browser-based execution, no community infrastructure, no spaced repetition integration, no time-based pacing structure. The untapped opportunity: no major platform does spaced repetition well for programming.
+
+### Innovation Research
+Three macro-trends: (1) browser-based Python via Pyodide eliminates setup friction, (2) modern Rust-powered tooling (uv, ruff) simplifies the developer experience dramatically, (3) AI tutoring is becoming table-stakes but must preserve cognitive engagement. Highest-ROI innovations: adopt uv, add Python Tutor visualization links, formalize progressive disclosure, teach type hints early.
+
+### Infrastructure Audit
+One critical bug: hardcoded absolute path in `tools/rebuild_navigation.py:10`. Test homogeneity mirrors the project template problem. Shell scripts have minor cross-platform issues. CI has no PR triggers. No ruff/formatting checks in CI.
+
+### Community Strategy
+The repo is private with 0 stars. The content is strong enough to compete, but distribution is the bottleneck. A specific launch playbook (social preview, Reddit/HN posts, GitHub Pages site) could drive initial traction. The learner-to-contributor pipeline (proven by Odin Project, freeCodeCamp) is the path to sustainability.
+
+---
+
+## Priority Tiers
+
+### Tier 0: Must-Fix (Bugs and Blockers)
+
+| # | Enhancement | Source | Effort | Impact |
+|---|------------|--------|--------|--------|
+| 1 | **Fix hardcoded path in `tools/rebuild_navigation.py:10`** — Replace `Path(r"E:\Web Development\learn.python")` with `Path(__file__).parent.parent` | Infra | 5 min | Critical |
+| 2 | **Fix broken links in `14_NAVIGATION_AND_STUDY_WORKFLOW.md`** — Elite extension links need `curriculum/` prefix | Content | 15 min | High |
+| 3 | **Fix unquoted `$py_files` in smoke scripts** — Word-splitting bug in `run_smoke_checks.sh:72` and `run_elite_smoke_checks.sh:45` | Infra | 15 min | Medium |
+| 4 | **Add `command -v rg` check to shell scripts** — Fail gracefully if ripgrep is missing | Infra | 30 min | Medium |
+| 5 | **Fix `XXXXX` placeholder in web-scraping module README** | Content | 5 min | Low |
+| 6 | **Extend portable path checker to scan `*.py` files** | Infra | 15 min | Medium |
+
+### Tier 1: Quick Wins (High Impact, Low Effort)
+
+| # | Enhancement | Source | Effort | Impact |
+|---|------------|--------|--------|--------|
+| 7 | **Add Python Tutor visualization links to concept docs** — Direct links to pythontutor.com examples for variables, loops, functions, collections, classes | Innovation | 2 hrs | High |
+| 8 | **Add "Reading Error Messages" concept doc** — Traceback anatomy, common errors, the `friendly` library | Innovation | 3 hrs | High |
+| 9 | **Create Python Feature Unlock chart** — Which features are introduced at each level (progressive disclosure) | Innovation | 4 hrs | High |
+| 10 | **Add AI usage guidelines per level** — No AI at Level 00, debugging hints at Level 3, pair programming at Level 7+ | Innovation | 2 hrs | Medium |
+| 11 | **Consolidate duplicate "Related exercises"/"Practice This" sections** in concept guides | Content | 1 hr | Medium |
+| 12 | **Add Advanced tier coding challenges** — 15 challenges for Level 6+ (generators, metaclasses, async, type system) | Content | 8 hrs | Medium |
+| 13 | **Improve quiz input normalization** — Accept `b`, `B`, `b)`, `(b)`, `option b` as equivalent | Content | 2 hrs | Medium |
+| 14 | **Create TRY_THIS.md for level-00 exercises** — 2-3 extension prompts per exercise | Content | 3 hrs | Medium |
+| 15 | **Update collections guide dict ordering** — Mark dicts as "Yes" for ordering (Python 3.7+) | Content | 15 min | Low |
+
+### Tier 2: Strategic Investments (High Impact, Medium Effort)
+
+| # | Enhancement | Source | Effort | Impact |
+|---|------------|--------|--------|--------|
+| 16 | **Replace 165 templated `project.py` files with bespoke starter code** — Each project gets code that matches its stated focus. Use expansion modules as quality benchmark. | Content | 40-80 hrs | **Transformative** |
+| 17 | **Replace 165 templated test files with project-specific tests** — Tests verify unique project requirements, not generic boilerplate | Content | 40-80 hrs | **Transformative** |
+| 18 | **Replace generic README body sections with project-specific instructions** — Alter/Break/Fix/Explain tailored to each project | Content | 20-40 hrs | High |
+| 19 | **Adopt uv as default package manager** — Replace all pip/venv instructions. Update setup guide, project templates, CI. | Innovation | 8 hrs | High |
+| 20 | **Introduce type hints early (Level 1)** — Function annotations, progress to generics by Level 4, add mypy to toolchain | Innovation | 8 hrs | High |
+| 21 | **Teach dataclasses before traditional classes** — Restructure OOP progression | Innovation | 6 hrs | Medium |
+| 22 | **Add match/case pattern matching** — Introduce at Level 2-3 after if/elif/else | Innovation | 4 hrs | Medium |
+| 23 | **Add PR-triggered CI** — Lightweight `py_compile` + link check + ruff on PRs | Infra | 4 hrs | High |
+| 24 | **Create social preview image** — 1280x640px branded image showing "261 Projects, Zero to Full-Stack" | Community | 2 hrs | High |
+| 25 | **Create TEACHING_GUIDE.md** — Semester mapping, fork instructions, assessment materials for educators | Community | 4 hrs | Medium |
+| 26 | **Make repo a GitHub template** — Enable "Use this template" for teachers | Community | 5 min | Medium |
+| 27 | **Create 5-10 "good first issue" issues** — Attract first contributors | Community | 1 hr | High |
+| 28 | **Structure GitHub Discussions categories** — Announcements, Q&A, Show Your Work, Curriculum Feedback | Community | 30 min | Medium |
+| 29 | **Expand certification doc** — Scoring rubrics, portfolio templates, defense formats for `50_CERTIFICATION_GRADE_COMPLETION_PROTOCOL.md` | Content | 4 hrs | Medium |
+
+### Tier 3: Major Initiatives (Transformative, Significant Effort)
+
+| # | Enhancement | Source | Effort | Impact |
+|---|------------|--------|--------|--------|
+| 30 | **Deploy GitHub Pages documentation site** — mkdocs-material or mdbook, searchable, navigable, dark mode | Innovation, Community | 16-24 hrs | High |
+| 31 | **Build Pyodide browser exercises for Level 00** — HTML page + CodeMirror + Pyodide, hosted on GitHub Pages | Innovation | 16-24 hrs | High |
+| 32 | **Automated progress tracking** — Script that checks test results, updates PROGRESS.md, generates dashboard | Innovation | 16-24 hrs | Medium |
+| 33 | **Create Python equivalents of shell CI checks** — Remove bash/ripgrep dependency for Windows learners | Infra | 16 hrs | Medium |
+| 34 | **SVG level completion badges** — Badge images for each level, displayable in GitHub profiles | Innovation | 8 hrs | Medium |
+| 35 | **Portfolio building guide** — How to present learn.python projects to employers, README templates | Community | 4 hrs | Medium |
+| 36 | **Career readiness track overlay** — Map levels to job roles (intern at Level 3, junior at Level 5, mid at Level 7) | Competitive | 4 hrs | Medium |
+| 37 | **"Fast track" entry point for experienced devs** — Skip Level 00, condense foundations, jump to projects | Competitive | 6 hrs | Medium |
+| 38 | **Spaced repetition integration** — Build review scheduling into the flashcard runner, add review prompts to curriculum flow | Competitive | 16 hrs | High |
+| 39 | **Launch Discord at 100+ stars** — Channels per level, show-your-work, study groups | Community | 8 hrs + ongoing | Medium |
+
+### Tier 4: Long-Term Vision
+
+| # | Enhancement | Source | Effort | Impact |
+|---|------------|--------|--------|--------|
+| 40 | Open Badges 3.0 verifiable credentials | Innovation | 40+ hrs | Medium |
+| 41 | marimo notebooks for data analysis levels | Innovation | 16+ hrs | Medium |
+| 42 | Full learning analytics platform | Innovation | 40+ hrs | Medium |
+| 43 | Mentoring network (learner-to-mentor pipeline) | Community | Ongoing | High |
+| 44 | Video companion content | Competitive | 40+ hrs | High |
+| 45 | GitHub Classroom integration | Community | 8+ hrs | Medium |
+
+---
+
+## Top 10 Highest-ROI Improvements
+
+Ranked by (impact on learner experience) x (feasibility) / (effort):
+
+1. **Fix hardcoded path in rebuild_navigation.py** — 5 minutes, prevents broken tool for every user
+2. **Add Python Tutor links to concept docs** — 2 hours, zero dependencies, massive visual learning boost
+3. **Create Python Feature Unlock chart** — 4 hours, helps every learner see the big picture
+4. **Replace 165 templated project.py/tests with bespoke code** — High effort but this IS the curriculum. Everything else is polish on top of this.
+5. **Adopt uv as default package manager** — Eliminates the #1 source of beginner frustration (venv/pip confusion)
+6. **Add "Reading Error Messages" concept doc** — Error messages are the first thing beginners encounter and the biggest source of frustration
+7. **Create social preview image and go public** — The content is ready. Distribution is the bottleneck. Everything else depends on visibility.
+8. **Deploy GitHub Pages site** — Makes the curriculum accessible without cloning, enables SEO, enables Pyodide exercises
+9. **Add PR-triggered CI + ruff checks** — Prevents regressions, signals active maintenance to contributors
+10. **Introduce type hints early** — Modern Python requires this; teaching it late creates bad habits
+
+---
+
+## Implementation Phases
+
+### Phase A: Critical Fixes (1 day)
+Items 1-6. Fix bugs, broken links, and infrastructure issues.
+
+### Phase B: Quick Wins (1 week)
+Items 7-15. Add concept docs, visualization links, feature chart, quiz improvements.
+
+### Phase C: Core Content Overhaul (2-4 weeks)
+Items 16-18. The project template replacement. This is the biggest undertaking and the highest-impact change. Consider doing this level-by-level, starting with Level 0 as proof of concept.
+
+### Phase D: Modernization (1 week)
+Items 19-22. Adopt uv, type hints, dataclasses, match/case.
+
+### Phase E: Launch Preparation (1 week)
+Items 23-29. CI improvements, social preview, teaching guide, GitHub features, good-first-issues.
+
+### Phase F: Public Launch
+Make repo public. Execute the community strategy launch playbook (Reddit, HN, Dev.to, Twitter).
+
+### Phase G: Platform Features (ongoing)
+Items 30-39. GitHub Pages, Pyodide, progress tracking, badges, portfolio guide.
+
+---
+
+## Verification Checklist
+
+- [ ] No hardcoded absolute paths in any tracked file
+- [ ] All navigation links resolve correctly
+- [ ] Shell scripts check for dependencies before using them
+- [ ] Every project has bespoke starter code matching its focus
+- [ ] Every project has tests that verify its unique requirements
+- [ ] Python Tutor links in all beginner concept docs
+- [ ] Feature Unlock chart exists and is linked from README
+- [ ] uv instructions in setup guide
+- [ ] Type hints introduced at Level 1
+- [ ] Social preview image set
+- [ ] PR-triggered CI active
+- [ ] GitHub Pages site deployed
+- [ ] Repo is public
+
+---
+
+## Source Reports
+
+| Report | File |
+|--------|------|
+| Content Quality Audit | `_audit_content_quality.md` |
+| Competitive Analysis | `_audit_competitive_analysis.md` |
+| Teaching Innovations | `_audit_innovations.md` |
+| Technical Infrastructure | `_audit_infrastructure.md` |
+| Community Strategy | `_audit_community_strategy.md` |
+
+---
+
+*Generated from 5 parallel research agents. Last updated: February 2025.*