Didactopus/docs/notebook-implementation-plan.md

Notebook Implementation Plan

This note turns the Notebook operating model into a concrete Didactopus implementation sequence.

It assumes the conclusions in notebook-operating-model.md:

• the Notebook is the durable knowledge layer
• learner products should derive from it
• distinctions, qualifications, constraints, and source roles are first-class
• public rendering must stay source-grounded and paraphrastic by default

Goal

Make Didactopus operate as a system with:

1. source-grounded ingestion and review
2. a durable Notebook concept network
3. learner, workbench, and public products derived from that network

The key implementation mistake to avoid is treating the Notebook as a static page generator. It should instead be the stable intermediate representation that other Didactopus products depend on.

Phase 1. Strengthen the source-grounded substrate

Primary concern:

• preserve the information needed to build a useful Notebook later

Required additions at this layer:

• source role classification:
  • overview
  • mechanism
  • nuance
  • controversy
  • argumentation
• distinction candidates:
  • A vs B
  • A does not imply B
  • B can occur without A
• learner-significance cues:
  • why this distinction matters
  • what misconception it prevents
  • what explanatory work it does
• first-class secondary products:
  • definitions
  • qualifications
  • constraints
  • quote candidates

Expected implementation targets:

• GroundRecall review/export payloads
• CiteGeist bibliography support and claim-support outputs
• source-adapter metadata from doclift and related import flows

Completion indicators:

• concept review payloads expose source roles
• distinction-like claims are tagged explicitly
• secondary products are inspectable without custom post-processing

Phase 2. Build Notebook-native concept structure

Primary concern:

• organize knowledge around explanatory hubs rather than narrow labels

Required additions:

• explicit hub-concept representation
• first-ring and second-ring neighborhood representation
• support for concept aliases without collapsing meaningful distinctions
• preferred-source selection by source role
• Notebook-level summaries built from grounded claims plus secondary products

Expected Didactopus targets:

• notebook_page payload shape
• hub/neighborhood builder logic
• pack emission for Notebook-facing artifacts

Completion indicators:

• a Notebook page can identify:
  • the primary hub
  • first-ring neighbors
  • key distinctions
  • preferred overview/mechanism/nuance sources
• bibliography topics no longer have to serve as the primary Notebook center

Phase 3. Make distinctions learner-facing

Primary concern:

• learning works better when concepts are contrasted, qualified, and scoped

Required derived-product features:

• distinction panels in learner workbench views
• definitions, constraints, and qualifications surfaced beside explanations
• “why this matters” cues for important conceptual differences
• quote/source-trail views for argumentation workflows

Expected Didactopus targets:

• learner workbench UI and backend payloads
• mentor/practice/evaluator session grounding
• lesson and activity generation

Completion indicators:

• learner-facing explanations can say not only what something is, but also:
  • what it is not
  • what it does not imply
  • what nearby concepts it is often confused with
• practice prompts can target misconceptions and contrastive understanding

Phase 4. Separate rendering contracts

Primary concern:

• the same Notebook knowledge should support different output modes without blurring their rules

Three rendering contracts should be explicit:

Notebook contract

• preserve concept structure
• preserve source trails
• preserve review context
• preserve distinctions and caveats

Workbench contract

• surface definitions, constraints, qualifications, and quote candidates
• prefer inspectability over polish
• retain enough detail for argumentation and source checking

Public exposition contract

• prefer paraphrase over copied wording
• mark all quotations explicitly
• attach source citation in display
• never present unmarked source wording as original Didactopus prose

Expected Didactopus targets:

• notebook-page rendering
• workbench payloads and views
• public publication/export paths

Completion indicators:

• public pages can be audited for quote marking and citation display
• workbench pages expose more raw source-oriented structure than public pages

Phase 5. Source-role-aware retrieval and ranking

Primary concern:

• different tasks need different kinds of support

Retrieval should be able to prefer:

• overview sources for first-pass orientation
• mechanism sources for explanatory detail
• nuance sources for qualifications and constraints
• controversy sources for dispute framing
• argumentation sources for rebuttal and debate workflows

This should influence:

• Notebook page support lists
• learner-session grounding
• workbench recommendation ordering
• quote-candidate selection

Completion indicators:

• the same concept can yield different ranked source sets for learn, review, argue, and publish contexts

Phase 6. Pack and publication alignment

Primary concern:

• the Notebook must become a stable export surface for other Didactopus flows

Needed outputs:

• Notebook-aware pack format additions
• workbench-friendly secondary-product exports
• publication-safe Notebook/public page export rules

Expected Didactopus targets:

• pack emission
• backend API payloads
• public export and frontend consumption

Completion indicators:

• packs can carry hub concepts, neighborhood structure, secondary products, and source-role metadata
• public and workbench consumers can rely on one shared substrate while rendering differently

Near-term priority sequence

The next practical Didactopus sequence should be:

1. make distinctions first-class in review/export payloads
2. add source-role metadata to Notebook-facing outputs
3. upgrade notebook_page to summarize hub, neighborhood, and secondary lanes
4. expose secondary-product and distinction views in learner/workbench flows
5. enforce explicit public citation and quote-marking contracts

What the pilot changed

Before the pilot, it was reasonable to think of the Notebook as a side product assembled from reviewed concepts.

After the pilot, the stronger view is:

• the Notebook should be the stable center of Didactopus knowledge organization
• learner products are better when built from Notebook structure
• short web captures and longer textbook sources should play different roles
• definitions, qualifications, constraints, and quotes are not optional extras

That change should guide both schema evolution and product decisions.