Add Notebook implementation plan
This commit is contained in:
parent
dd109ec93c
commit
56bded1313
|
|
@ -0,0 +1,235 @@
|
|||
# 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](./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.
|
||||
|
|
@ -178,3 +178,6 @@ Near-term Didactopus work should therefore prioritize:
|
|||
|
||||
The notebook is not the only Didactopus output. It is the durable center that
|
||||
lets the other outputs stay grounded, explainable, and pedagogically useful.
|
||||
|
||||
For the implementation sequence that follows from this model, see
|
||||
[notebook-implementation-plan.md](./notebook-implementation-plan.md).
|
||||
|
|
|
|||
Loading…
Reference in New Issue