Add wiki optimization research for team training environments

knowledge/wiki-optimization-research.md

@@ -0,0 +1,169 @@
+# Wiki Optimization — Team Training Environments
+
+## The Problem With Our Current Structure
+
+### Current State
+- Files buried in subdirectories: `entities/students/bruno.md`
+- Compile scans `entities/` root only → entities count = 0
+- Folders create rigid hierarchy → knowledge doesn't connect across siloes
+- 90 sources but they don't cross-reference meaningfully
+
+### What We're Missing
+The wiki's power isn't in folders — it's in **links**. A wiki that surfaces data usefully for a team training environment needs:
+
+1. **Atomic notes** — one concept per file, linked to everything related
+2. **Topic notes** — "hub" pages that aggregate links to related content
+3. **Training paths** — sequences of notes that guide learning
+4. **Entity profiles** — student/mentor pages that track skills + progress
+
+---
+
+## Three Fix Options
+
+### Option A: Move Files Up (Minimum Fix)
+**What:** Move `entities/students/bruno.md` → `entities/bruno.md`
+
+| Pros | Cons |
+|------|------|
+| Quick fix | Solves compile only, not structure |
+| Entities show up | Rigid folder hierarchy persists |
+| Low risk | Doesn't enable cross-topic views |
+
+**Verdict:** Tactical patch. Doesn't fix the real problem.
+
+---
+
+### Option B: Flat Structure + Topic Hubs (Recommended)
+**What:**
+1. Move student files to `entities/` root
+2. Create **topic hub pages** that link to relevant entities + sources
+3. Use Obsidian Dataview to create dynamic skill-tracking views
+
+**Example topic hub:**
+```
+# PathPlanner Training Hub
+[[bruno]] — working through PathPlanner basics
+[[riley]] — completed intro module
+[[photonvision]] — integrated with autonomous routines
+[[mothman-robot-code]] — YAGSL swerve implementation
+
+## Learning Path
+1. [[systemcore]] — understand the controller first
+2. [[swere-modules]] — then how the drivetrain works
+3. [[photonvision]] — then vision-based positioning
+4. PathPlanner → finally, how to program paths
+```
+
+| Pros | Cons |
+|------|------|
+| Compile works | Requires more setup upfront |
+| Teams see learning paths, not files | Topic hubs need maintenance |
+| Cross-topic views via Dataview | — |
+| Scales to any number of students | — |
+| Each hub is a training module | — |
+
+**Verdict:** Best for our scenario. Chris teaches — he needs learning paths, not file browsers.
+
+---
+
+### Option C: Recursive Compile Config
+**What:** Configure the wiki plugin to recurse into subdirectories
+
+| Pros | Cons |
+|------|------|
+| Keeps subdirectories | Requires config change |
+| Existing structure preserved | May break with OpenClaw updates |
+| — | Doesn't solve cross-linking problem |
+
+**Verdict:** Avoid. Kicks the problem downstream.
+
+---
+
+## Recommendation: Option B
+
+**Why Option B surfaces data most usefully for our scenario:**
+
+Chris is a teacher. The Fabric watches all silos. The wiki should answer questions like:
+
+| Question | How Option B Answers It |
+|----------|------------------------|
+| "Who's learning PathPlanner?" | [[pathplanner-hub]] → [[bruno]] + [[riley]] |
+| "What does a new student need to learn?" | Topic hub shows prerequisites + links |
+| "Where are the gaps in our training?" | Hub pages with missing/unfinished links |
+| "What did Bruno complete?" | Dataview query: student + status + date |
+| "Show me all sensor-related docs" | [[sensors-hub]] → links to all sensor sources |
+
+**Topic hubs we'd need:**
+
+| Hub | Purpose | Links |
+|-----|---------|-------|
+| `swere-training-hub` | Drivetrain learning path | Bruno, Riley, MK4i, NEO Vortex, YAGSL |
+| `vision-training-hub` | Camera + AprilTag setup | PhotonVision, MegaTag, AprilTag field layout |
+| `pathplanner-hub` | Autonomous programming | Student progress, YAGSL, Mothman code |
+| `electrical-hub` | Wiring + CAN bus | SPARK Flex, CANcoder, PDH, Canjectors |
+| `cad-training-hub` | Fusion 360 learning | Bruno, Riley, Fusion 360 module |
+
+---
+
+## Implementation Steps
+
+### Step 1: Fix Entity Compile (5 min)
+```bash
+cd /home/topher/.openclaw/wiki/main
+git mv entities/students/bruno.md entities/bruno.md
+git mv entities/students/riley.md entities/riley.md
+git commit -m "Flatten entities structure for compile"
+git push
+```
+
+### Step 2: Create Topic Hub Pages (ongoing)
+Start with the most important hub — the one Chris teaches from most:
+
+**`training/hubs/swere-training-hub.md`**
+- Links: MK4i, NEO Vortex, SPARK Flex, YAGSL, Bruno (learning), Riley (completed)
+- Learning path with prerequisites
+- Status indicators per student
+
+### Step 3: Add Frontmatter for Dataview
+Add to each student profile:
+```yaml
+---
+type: student-profile
+track: swerve
+skills:
+  - fusion-360: intermediate
+  - pathplanner: beginner
+  - welding: beginner
+status:
+  pathplanner: in-progress
+  swere-basics: completed
+---
+```
+
+Then Dataview can query: "Show all students with `skills.pathplanner: beginner`"
+
+---
+
+## Research Path for Chris
+
+This IS the research path. The "fix" isn't a wiki plugin config — it's **restructuring the wiki around how Chris teaches**:
+
+1. **Atomic notes** per hardware concept (we already have this)
+2. **Topic hubs** that aggregate + sequence learning (we're missing this)
+3. **Entity profiles** with structured skill tracking (we have the files, wrong location)
+4. **Training paths** that show prerequisite chains (needed for system to surface gaps)
+
+The Fabric then detects gaps by watching:
+- Which hub links are broken?
+- Which student profiles show no recent progress?
+- Which hub has no topic hub page yet but students need it?
+
+---
+
+## Key Insight
+
+**Folders are for files. Hubs are for learners.**
+
+Chris teaches. The wiki should organize around what students need to learn, not where files live. Topic hubs do that — they group related content from across all silos into coherent learning paths.
+
+**Option B is the fix.** Want me to start with the swerve training hub? 🎓