The wikiwiki principle: lowest-friction capture, then progressive refinement in place

Type: kb/types/note.md · Tags: type-system

The KB type hierarchy is a codification ladder for thoughts. Its design principle comes from Ward Cunningham's original wiki: make saving a thought trivially easy, then make refining it easy — in place, not by moving it elsewhere.

Evidence

  1. The original wiki. Cunningham's WikiWikiWeb (1995) was built around two properties: anyone can create a page instantly (lowest capture friction), and anyone can edit it later (progressive refinement). The name "wiki" comes from Hawaiian "wikiwiki" meaning "quick" — speed of capture was the core design value. Pages started rough and improved through repeated editing, not through a draft→review→publish pipeline.

  2. Our type ladder mirrors this. The type system supports the same pattern:

  3. text — no frontmatter, just write. Zero friction, like creating a wiki page.
  4. note — add valid frontmatter with description and type: kb/types/note.md, then develop the title and connections. Now findable.
  5. structured-claim — add Evidence/Reasoning/Caveats sections. Now verifiable.

Each step adds structure only when the thought has earned it. The same logical artifact grows structure in its current collection; conversion may normalize its filename and repair backlinks rather than preserving a mismatched path.

  1. Verification stays orthogonal. A structurally complete structured-claim may still lack user-verified; shaping, semantic review, and explicit human attestation are distinct operations. Structure can be refined without manufacturing a commitment signal.

Reasoning

A half-formed intuition doesn't need Toulmin sections — it needs to exist before it's forgotten. A mature argument that other notes depend on as a premise does need sections — it's load-bearing and must be trustworthy. The wiki principle says: don't force mature structure at capture time, because friction prevents capture. Don't leave mature arguments unstructured, because you can't verify them.

The key property is refinement in place. A text file becomes a note by adding valid note frontmatter. A note becomes a structured-claim by adopting that type's pointer and sections. No content migration, copy, or publication pipeline is required. Conversion may normalize the filename within the same collection, but it repairs backlinks and preserves the artifact's body and Git history. This makes refinement cheap enough to actually happen — the same insight Cunningham had about wiki pages.

This connects to codification: codification is the general pattern (stochastic → deterministic), the wiki principle is the UX requirement that makes it work (each step must be low-friction and in-place).

Caveats

  • Wikis have a decay problem. The original WikiWikiWeb suffered from stale pages nobody maintained. Explicit replacement links, retired-note prose, and review freshness expose some decay, but the risk remains — low capture friction means high volume, and curation must keep up.
  • "In place" has limits. A text file that grows into a 500-line structured-claim might be better split. The principle is "refine in place when possible," not "never split."
  • The ladder is a library pattern. Refinement-in-place assumes documents move toward permanence — accumulating structure, becoming more connected, staying in the KB. Workshop documents (tasks, decision threads, experiments) follow the opposite trajectory: they consume value over time and end by being archived or discarded. The wikiwiki principle applies to knowledge capture, not work-in-motion.

Relevant Notes: