Knowledge Point Tree

---
name: knowledge-point-tree
description: Build a flat, exhaustive "point tree" of every enumerable knowledge point in a bounded body of material (a textbook, a certification syllabus, a spec, an API surface, a legal code), so a learner facing a brand-new field can see the whole board at once instead of drowning in unknown unknowns. Use this whenever someone says they are starting a new field and feel lost, can't tell where things belong, keep confusing similar-sounding terms, want a "framework" or "整体框架" or "knowledge map" of a subject, are prepping for a certification exam, or hand over a textbook/PDF/spec and ask what's in it. Also use when someone asks to summarize all the numbered lists, categories, or classifications in a document. Do NOT wait for the words "point tree" — the trigger is the feeling of being overwhelmed by an unfamiliar domain, or the presence of a bounded authoritative source that needs mapping.
---

# Knowledge Point Tree

## What this solves

The hardest moment in a new field is not difficulty — it's **not knowing what you don't know**. A learner reads chapter 9, then chapter 16, and has no idea the two are talking about the same concept at different levels. Similar terms blur. Nothing has a home.

A point tree fixes orientation before it fixes knowledge. It is a **flat, exhaustive inventory of every enumerable group** in the material — "the seven principles of X", "the four classifications of Y", "the three layers of Z" — organized by nothing but chapter, with all sub-numbering flattened away.

It is not a table of contents. A TOC tells you a section exists. A point tree tells you **what is inside every section, at the grain the field itself uses**.

The learner ends up with initial literacy: they can now hear an unfamiliar term and place it. That is the deliverable.

## Why it works

Understanding the mechanism matters more than following the steps, because it tells you what to do when the material doesn't fit the recipe.

**Learning a field is not a sapling growing into a tree.** It is not trunk first, then branches, then leaves. Everything comes up faintly at once — like a progressively-loaded image that appears whole at low resolution and then sharpens all over, rather than rendering top to bottom. The point tree is that low-resolution first pass: the entire field, visible at once, in no detail whatsoever.

This has empirical backing. Ausubel's *advance organizer* work showed that a coarse high-level framework given beforehand improves retention of the detail that follows. Bransford and Johnson's 1972 study is the sharper demonstration: a passage describing an everyday procedure is nearly unrecallable when read without its title, and recall jumps when the title comes first. Same sentences, same reader — the difference is whether a blurry whole existed to attach them to.

**One correction to the intuition, because it changes how the method is used.** It is tempting to picture stray details waiting patiently for the trunk to arrive and then connecting up. They don't wait. Information with nothing to attach to is simply lost. The details that seem to "find their place later" were already hooked onto something at the time — an analogy, a prior experience, an adjacent concept the learner already held.

So the tree's real function is not retroactive collection. It is **hanging the hooks in advance**, densely enough that anything arriving later lands on at least one. This is why counts belong in group names: a count is itself a hook, and an empty slot in a known-size set is a hook with a shape.

**The benefit is front-loaded, and the tool should retire.** Bjork's work on desirable difficulties runs the other way: past the early phase, frictionless scaffolding becomes a crutch and produces fluency illusions — the feeling of knowing without the ability to retrieve. The coverage measurement in Step 4 is also the retirement signal. When the tree's ceiling is quantified, the remaining work is practice and production, not recall, and continuing to polish the tree is avoidance.

## When to use it, and when not

**Strong fit** — the material is bounded, authoritative, and taxonomy-heavy:
- Certification and licensing exams with an official textbook
- Specs and standards (RFCs, ISO, protocol docs)
- API and framework surfaces
- Legal codes, medical classifications, security frameworks, compliance regimes

**Weak fit** — say so rather than producing a tree that will mislead:
- Skill domains where knowing ≠ doing (programming, writing, design, clinical practice)
- Derivation-based fields (mathematics, physics) where the value is in the chain, not the list
- Fields with no bounded canonical source, where an "exhaustive" tree is a lie
- Judgment-heavy fields where the real content is in the trade-offs between the items, not the items

For weak-fit material, offer the honest alternative: a concept map of relationships, or a worked-example progression.

## The five-step loop

### Step 1 — Lock a bounded source

One canonical source, with edges. A textbook, a syllabus, one spec. Boundedness is what makes "exhaustive" meaningful; a web scatter cannot produce a panorama.

If the user hands over a PDF, use it. If they don't have one, ask what the field's canonical text is before scraping the internet. A tree built from mixed sources inherits their contradictions without flagging them.

### Step 2 — Extract from the full text, never the TOC

This is the step most likely to be done wrong, in two different ways.

**First: the TOC is not the tree.** It gives section titles; **the enumerable points live in the body**. A tree built from a TOC looks convincing and is worthless — it says a section exists and nothing about what is inside it, which is the exact gap this method exists to close. Read the whole thing.

TOCs arrive in two disguises and both must be filtered: Markdown contents pages are runs of anchor links, while PDF contents pages use dot leaders (`1.1 Overview ......... 12`) that a marker regex happily reads as numbered points.

**Second: identify what form this source uses to carry enumeration, before extracting anything.** This is the failure that testing actually caught, and it is silent — the wrong form returns a small, plausible-looking result rather than an error.

| Source type | Enumeration lives in |
|---|---|
| Textbook, exam prep | Numbered lists (`(1)`, `1.`, `①`) **and** comparison tables |
| Spec, RFC, standard | **Field tables** — often with no list markers anywhere |
| API / library reference | Signature blocks, parameter tables, type definitions |
| Legal code | Numbered articles and clauses — in CJK texts, `（一）（二）` and `第X条`, not Arabic numerals |
| Clinical / taxonomic reference | Classification tables and criteria sets |

Skim a few representative sections and answer "what shape does a group take here?" before running anything. On one OpenAPI spec, list-marker extraction returned 8% of the body and every line of it was table-of-contents; the real content was in `Field Name | Type | Description` tables the extractor could not see. The method's own "strong fit" list includes specs and API surfaces, so this is not an edge case — it is half the intended input.

**Most sources are mixed, and the minority form is often the valuable one.** A textbook is overwhelmingly numbered lists, but its side-by-side comparison tables — SAAM vs ATAM, Lambda vs Kappa — are the densest, most-tested groups in the book and are exactly what a learner confuses. Picking whichever form is more common and discarding the other throws away the best material. Extract both unless one is genuinely absent.

**Tables extracted from PDFs need manual repair.** `pdftotext` renders them as space-aligned columns; wrapped cells split across rows, merged headers collapse, and row/column identity is often lost. A space-column heuristic finds the blocks but cannot reliably reconstruct them. Treat PDF table output as a pointer — "there is a table here, go look at it" — and rebuild the important ones by reading the page. Markdown and HTML tables extract cleanly; PDF tables do not.

Mechanically:
1. Extract full text (`scripts/extract_points.py` handles PDF, Markdown, plain text).
2. Strip page furniture — headers, footers, bare page numbers, figure captions.
3. Strip the TOC.
4. Strip exercise and answer sections. They roughly double the volume, though they sometimes contain points the body omits — see Step 4.
5. Extract by form. The script auto-detects lists vs tables and reports the counts and yield; a yield under ~3% of body means the form guess was wrong, not that the source is thin.

Read the script's output rather than trusting it. Layout quirks break naive matching — headings split across lines, lists interrupted by figures, escaped delimiters inside cells.

### Step 3 — Write the tree

Format, per group:

```
**<group name, with the count>：**
（1）...
（2）...
（3）...
```

When the source carries groups as tables, the table's subject is the group name and each row is one point. Keep the column labels — they are the group's schema, and often the thing that distinguishes two similar-looking tables:

```
**Info Object — 6 fields** (Field Name | Type | Required)
（1）title | string | REQUIRED
（2）summary | string | —
...
```

Rules that matter:

- **Only chapter-level hierarchy.** No 1.1, no 1.1.2. Groups sit flat under their chapter.

  The convenience argument for this — flat is easier to scan — is the weak one. The real reason is that **"point tree" is a misnomer, and flattening is the honest response to it.** Real knowledge structures are graphs with cycles, not trees. A tree forces every concept under exactly one parent, and fields routinely violate that: the same term appears at three levels in three chapters, meaning something different each time. That collision is usually the learner's single biggest source of confusion. Imposing nesting invents a hierarchy the field does not have, and the invented hierarchy is precisely what makes similar terms blur together.

  Flat groups plus a separate disambiguation map (see Output shape) carry what a tree cannot: the lateral edges.
- **Put the count in the name.** "The seven principles of cloud-native" is self-checking; when reciting, the learner knows when one is missing. Counts are the tree's error-detection.
- **Preserve the source's own wording and its own numbering order.** Do not improve, reorder, merge, or modernize. If the source says "error avoidance" where the wider field says "error prevention", write "error avoidance" — the learner is being tested on this source, and a silently corrected term is a trap.
- **Only include what is genuinely enumerable.** Prose definitions, worked examples, and derivations do not belong; forcing them into list shape produces fake structure.

### Step 4 — Measure the gap, out loud

**This is the step that separates a useful tree from a comforting one.** A tree always feels more complete than it is. Quantify it before the learner over-trusts it.

Take a real assessment set — a past exam, a practice test, a set of real tasks — and classify every item:

| Class | Meaning |
|---|---|
| A | Answerable directly from a group in the tree |
| B | Needs body prose the tree structurally cannot hold (definitions, comparisons, "which statement is false") |
| C | Calculation, derivation, or reasoning |
| D | Outside the tree's scope entirely |

Report the A-rate as the tree's honest coverage, and name what falls in B/C/D. In one real run on a systems-architecture certification, a carefully built tree hit **48% of multiple-choice items directly** — genuinely useful, and nowhere near sufficient. Saying that number plainly is more valuable to the learner than the tree itself.

Two things this step reliably surfaces:
- **Points that live only in exercises.** Some material introduces a taxonomy only in a practice question. Include these, marked as such.
- **Points the wider field considers standard but this source omits.** Mark these too — the learner needs to know they must go elsewhere.

### Step 5 — Fill in details, gap-driven

Detail-filling is now targeted rather than a second full pass. The B/C/D classes from Step 4 are the work queue, ordered by how many assessment items each unlocks per hour spent.

Tell the learner where the tree stops being the right tool. Enumerable structure is the tree's whole competence; judgment, calculation, and production need practice, not recall.

## Provenance marking

Every group carries a tag. The learner's trust should be calibrated per-line, not global.

- **[source]** — verbatim in the body of the canonical source
- **[exercise]** — appears only in a practice problem or its explanation
- **[external]** — not in this source, but standard in the field and commonly assessed

Sources contradict themselves more often than people expect. When they do, **present both versions and name the discrepancy** rather than silently choosing. In the run mentioned above, one textbook gave two incompatible taxonomies of architecture styles in different chapters — one with six families plus an extra, another with five and different members. Both were assessable. Reconciling them would have hidden a real hazard.

## Verification is mandatory

A point tree's entire value is that the learner will memorize it without checking. Shipping an unverified one causes direct harm — they will confidently write down something wrong.

After writing, sample at least 40–60 groups at random and string-match each back against the source text. Normalize whitespace first; PDF extraction inserts breaks mid-phrase and will produce false failures. Report the pass rate to the user.

When a check fails, distinguish a formatting artifact from a real error, and fix real errors in the file rather than in conversation only.

If the user challenges a specific point, **go back to the source and check** rather than defending or conceding from memory. Both errors are live: in the run above, one correction was right and a subsequent "correction" was itself wrong — a group of nineteen items was declared absent after only the first two subsections were checked. Verify the full span before ruling something out, and correct the correction when it happens.

## Output shape

Two files, because they serve different moments:

1. **The point tree** — flat, exhaustive, source-ordered. Used for reciting and for spotting gaps.
2. **A disambiguation map** — the confusable clusters, side by side. Which similar-sounding terms live at which level, what distinguishes them, which are actually the same thing under two names.

The second file is where the "I keep mixing these up" pain actually gets solved, and it is not optional. It carries the lateral edges the flat tree deliberately drops — the graph structure the tree shape cannot hold. A point tree shipped without it leaves the learner's main problem untouched.

Build it from the terms that appear in more than one chapter, from near-synonyms the source uses loosely, and from any pair whose distinction the source states only once in passing.

Add mnemonic hooks where they fall out naturally — first-character strings for ordered lists, a one-line contrast for confusable pairs. Do not manufacture them for every group; a forced mnemonic is one more thing to remember.

## Scale note

Full-text extraction for a 300-page source runs to roughly 150–200k characters of body text after stripping. Work in batches by chapter and write to file incrementally rather than holding it all in context. Report progress as you go — this takes real time and the user should see it moving.

## Bundled resources

- `scripts/extract_points.py` — PDF/text → cleaned body → enumerated-line extraction with context. Run `python extract_points.py --help` for usage. Treat its output as a draft to read and correct, not a finished tree.