docs: vision & plans — graph construction, session experience, presentation, roadmap
Captures 2026-08-22 decisions: hybrid live-emission + consolidation graph construction (reversing the vault doc's teacher-untouched rule), one substrate merged across sessions, structured plan-tree tools (mermaid demoted to ad-hoc), probe/teach phase separation with collapsed teach checks, right-panel tree view, LaTeX delimiter switch plan, and a dependency-ordered roadmap.
This commit is contained in:
Amos
+114
@@ -0,0 +1,114 @@
|
||||
# Learning Harness — Vision & Plans
|
||||
|
||||
Living document. Started 2026-08-22, capturing the current vision and all agreed decisions. Amend as things evolve.
|
||||
|
||||
Prior art: `knowledge graph design.md` in the Obsidian vault (2025-08-20 ideation) — still canonical for the epistemic model (known vs understood, requires/supports, event ledger, calibration rubric, merging policy). This document records what today's decisions **amend** in it, and adds the session-experience and presentation layers the original doc deferred.
|
||||
|
||||
---
|
||||
|
||||
## 1. The knowledge graph — the centerpiece
|
||||
|
||||
Everything the learner learns accumulates into one persistent, cross-domain graph. It is the home page of the app and the heart of the system: structure builds out visibly over time, and the data supports frontier expansion, what-next queries, repairs, unlock-value (per the original design doc).
|
||||
|
||||
### Critical requirement: frequent updates
|
||||
|
||||
The graph updates **continuously, not per-session**. A learner who answers a few questions and leaves without "finishing" a session must still see something new on the home page. Partial sessions deposit value. This requirement drove the construction decision below.
|
||||
|
||||
### Construction: live events + background consolidation (DECIDED)
|
||||
|
||||
**Amendment to the original design doc.** The original doc stated "the teacher agent is never modified; all graph-building is post-hoc," and rejected live structured emission as too much cognitive load. That is now **reversed**, because the teacher will be maintaining a formal plan tree anyway (§2) — once it does, live emission is nearly free, and it's the only way to satisfy the frequent-updates requirement.
|
||||
|
||||
- **Live:** the teacher maintains the session's dependency tree via structured tools and tags quiz outcomes to tree nodes as they happen. The home graph reflects this in near real time.
|
||||
- **Background consolidation (lightweight, frequent):** cross-session node merging (embed → kNN → LLM adjudication, conservative — duplicates over wrong merges), calibration rubric application, and edges that were articulated only in prose. Runs on navigation home / idle — not as a heavy per-session batch.
|
||||
- The original three-stage transcript-extraction pipeline survives only as (a) the retroactive bootstrap over old session files, (b) the audit/faithfulness net.
|
||||
|
||||
### One substrate, merged across sessions (DECIDED)
|
||||
|
||||
A single node model: propositions at one-reasoning-step grain, `requires`/`supports` edges, no edge scalars. A session's plan tree **is** a session-scoped subgraph. The global graph is the merge of all session trees:
|
||||
|
||||
- **v1 (bare bones):** merge = naive union. No adjudication yet.
|
||||
- **later:** the embed + LLM-adjudication merge pipeline from the design doc (the quiet superpower: cross-session/cross-domain edges only ever get created here).
|
||||
|
||||
Carried over unchanged from the design doc: known (evidence property) vs understood (derived structural property); event ledger as source of truth with derived state recomputed; anchored 5-level calibration rubric; misconception nodes as first-class structure; candidate node class for frontier territory.
|
||||
|
||||
### Rendering (direction; library choice pending research)
|
||||
|
||||
- **Lightweight above all.** Runtime performance matters; interactivity does not.
|
||||
- Physics only for **placement + stabilization** (Obsidian-style settle), then the graph goes static — near-zero idle CPU. No dragging, no force sliders, no editing interactions.
|
||||
- Pan + zoom (trivial), labels appearing at zoom thresholds.
|
||||
- Target feel: the Obsidian graph — dots, thin edges, settled physics.
|
||||
- Layout architecture options under research: client-side simulation on mount vs. precomputed coordinates (server/worker, e.g. d3-force or forceatlas2 run headless) with "run N ticks then freeze."
|
||||
- Candidates under research: sigma.js (WebGL), d3-force + custom canvas renderer, cosmos/cosmograph, react-force-graph-2d. A research report lands separately and the decision gets recorded here.
|
||||
|
||||
### Home page
|
||||
|
||||
The graph view replaces the current placeholder. v1: all nodes from all sessions (naive union), node color/shape by state class (taught / probed / known / not-held / candidate later), pan/zoom, labels at zoom. Clicking a node → the session(s) that touched it (cheap version: title list). Everything richer (frontier glow, rot map, blast radius) comes after the consolidation pipeline exists.
|
||||
|
||||
---
|
||||
|
||||
## 2. The session experience — not a generic chat
|
||||
|
||||
Goal: a learning session must look and feel structurally different from a ChatGPT/Claude conversation. The differentiator is making the session's **dependency tree a formal, visible, agent-editable object** rather than a throwaway mermaid sketch.
|
||||
|
||||
### The formal plan tree (DECIDED)
|
||||
|
||||
- The agent authors the tree via **structured tools** — `add_node`, `add_edge`, `reparent`, `remove_node`, `set_current`, … — schema-validated, with stable node identity across edits. Mermaid text as the source of truth was rejected: edits would be text surgery and identity would drift.
|
||||
- The agent may edit the tree mid-session at its own initiative (detour when the learner asks something worth exploring, go deeper, prune) — that power is explicit.
|
||||
- **"Where we are"** is tracked as structured state (a `set_current` tool), not inferred from the transcript.
|
||||
- **Mermaid survives only for ad-hoc lesson diagrams** (flows, cycles, comparisons) that are not the plan tree. Its rendering quality must improve (integrated display, working zoom/pan — current code-block-ish rendering is unacceptable), but it's now a peripheral concern.
|
||||
|
||||
### Two phases, clearly separated (DECIDED)
|
||||
|
||||
- **Probe** and **teach** are the two real phases; planning is not a phase, just a moment (maybe a small indicator).
|
||||
- The agent signals the probe→teach transition with a structured marker → **visible divider in the transcript**.
|
||||
- **Probe-phase questions auto-open** (as now — they are the substance of probing).
|
||||
- **Teaching-phase check questions start collapsed** behind a "Check your understanding" reveal button. Rationale: a question popping up mid-lesson pressures the learner to answer immediately; the learner should read the teaching first and open the check when ready.
|
||||
|
||||
### Persistent tree view (DECIDED)
|
||||
|
||||
- **Right-side collapsible panel** in the session UI: the whole tree, at all times, with clear visual separation between nodes and states (done / current / next / upcoming), collapsible to a thin strip.
|
||||
- This panel and the agent's tools share the same underlying data — the tree is one object with two faces (agent edits it, UI renders it).
|
||||
|
||||
---
|
||||
|
||||
## 3. Presentation layer (noted, not yet scheduled)
|
||||
|
||||
- **LaTeX delimiters: switch to the ChatGPT convention.** Inline math `\(...\)`, display math `\[...\]`. The single `$` is retired from math duty and reserved for currency (ending the dollar-sign hazard for good, on both teacher output and eventually user input). Technical path: preprocess `\(...\)`/`\[...\]` → remark-math-compatible form (or a dedicated micromark extension), plus a system-prompt update. The old `$`/`$$` contract dies with this change.
|
||||
- **Line breaks bug:** lesson text loses single line breaks (markdown semantics collapse them — likely fix: `remark-breaks`, or prompt-level blank-line discipline; verify and fix).
|
||||
- **Lesson-content formatting:** richer, more structured presentation of teaching blocks (headings, callouts, worked examples) — direction noted, specifics TBD.
|
||||
- **PARKED (long-term):** a rudimentary LaTeX editor / live preview in the composer so the learner can send formatted math.
|
||||
|
||||
---
|
||||
|
||||
## 4. Roadmap (dependency-ordered)
|
||||
|
||||
1. **Plan-tree tools + session state** — structured tools, tree persisted in the chat store, `set_current` tracking. (Everything else depends on this.)
|
||||
2. **Bare-bones global graph + home view** — live emission from tree tools into a graph store, naive-union merge, home page renders it with the chosen lightweight renderer. *This is the "see something appear even from a partial session" milestone.*
|
||||
3. **Phase separation** — probe/teach marker, transcript divider, collapsed teach-phase checks.
|
||||
4. **Right-panel tree view** — persistent, current-position highlight.
|
||||
5. **Background consolidation** — merge adjudication, calibration, prose-only edges.
|
||||
6. **Presentation fixes** — LaTeX delimiters, line breaks, mermaid integration.
|
||||
7. **Later:** frontier expansion + what-next queries (new territory / repairs / conversions), spaced repetition on the event ledger, practice exercises, Electron.
|
||||
|
||||
---
|
||||
|
||||
## 5. Open questions
|
||||
|
||||
1. Graph rendering library + layout architecture (research in flight — record decision here when it lands).
|
||||
2. What exactly the naive-union v1 shows for overlapping topics across sessions (duplicate nodes acceptable until consolidation? — presumed yes, cosmetic only).
|
||||
3. How the probe phase's questions map onto tree nodes when no tree exists yet (probe happens *before* the plan is written — do probe outcomes attach to a provisional node set, or to the eventual tree retroactively?).
|
||||
4. Home-graph v1 interactions beyond pan/zoom (node click → session list? — presumed cheap yes).
|
||||
5. Grain mismatch frequency (`subsumes`-style relations) — per original doc, measured by data, not pre-solved.
|
||||
6. Aggregation semantics for understanding (min / mean / two-level) — fit on real data, per original doc.
|
||||
|
||||
---
|
||||
|
||||
## Amendments to the vault design doc (2025-08-20) — summary
|
||||
|
||||
| Original | Now |
|
||||
|---|---|
|
||||
| Teacher never modified; graph built post-hoc | Teacher emits structured data live; background pass consolidates |
|
||||
| Updates per completed session | Continuous; partial sessions deposit value |
|
||||
| Mermaid DAG as the plan artifact | Structured tools as source of truth; mermaid only for ad-hoc diagrams |
|
||||
| UI deferred, "not important" | UI exists (Next.js, v3.4); the graph view is the app's home page |
|
||||
| pi as core dependency | pi removed; harness is standalone Next.js + Vercel AI SDK |
|
||||
Reference in New Issue
Block a user