Friction audit (epic #231, Phase 0)¶
Purpose. Map ZettelFlow's entire user-facing surface to the job each element does, flag every overlap, and propose the one primary path per job. This is the evidence base for the "one obvious path" epic (#231); every later phase should cite a row here.
Stance: consolidate & hide. The manifesto asks us to preserve people's work and compatible workflows, not every redundant interface. This audit retains capabilities while exposing one obvious path and moving duplicates out of the way; it does not authorize deleting user work or breaking established workflows.
Two different "frictions" — do not confuse them. This page is about operational friction: duplicated paths, unclear entry points, steps that cost the user effort for no thinking in return. That kind is removed. Deliberate (cognitive) friction — asking for your reading before the system reveals its own — is the opposite: it is added on purpose where judgement is at stake (constitution §XII, manifesto).
Method¶
Counted from source on main: addCommand ids, registerView names, the community catalog types, DEFAULT_SETTINGS, and the single ribbon action. No behavior changed by this document.
1. Entry points¶
| Surface | Count | Reality |
|---|---|---|
| Ribbon | 1 | One all-in-one "Open ZettelFlow" button; its menu leads with Create note and lists the surfaces (#271). Note-creation is also a hotkey-bindable command (open-workflow). |
| Sidebar views | 13 | Reachable from the one ribbon menu (#231) and each show-* command; opened as main-area tabs (#270). |
| Commands | ~23 | ~12 are just show-<a-view>; the rest are actions + install paths. |
Update (#268 Phase 7): the two ribbon icons were unified into one all-in-one button (#271), views now open as normal tabs (#270), and the ~12 sidebar views are being collapsed into 4 surfaces with modes (#272). This section describes the pre-consolidation baseline.
Finding F1. The 13 views have no discoverable entry point — a user must know 12 command names. → Phase 2: Home becomes the front door that surfaces/links them.
2. Sidebar views — the "understand my knowledge" cluster¶
| View (command) | The question it answers | Overlaps |
|---|---|---|
home (show-home) | "Where do I start today? what's next?" | superset of dashboard + resurface + open-questions |
knowledge-dashboard (show-knowledge-dashboard) | "What's the state of my system? what next?" | Home, slipbox-health |
slipbox-health (show-slipbox-health) | "Orphans, dead-ends, knowledge debt, balance" | dashboard, Home |
knowledge-map (show-knowledge-map) | "What are my hubs/clusters?" | concept-nav (both graph views) |
concept-nav (show-concept-nav) | "Walk my graph by typed relation" | knowledge-map |
discoveries (show-discoveries) | "Surprising connections to make" | resurface (both surface connections) |
resurface (resurface-related-notes) | "Older related notes worth revisiting" | discoveries |
open-questions (show-open-questions) | "Every unanswered question" | Home (a Home panel already) |
evolution-timeline (show-evolution-timeline) | "How did this idea evolve?" | — (distinct, per-note) |
evidence-map (show-evidence-map) (experimental) | "Grounded synthesis of a note" | — (distinct) |
thinking-heatmap (show-thinking-heatmap) | "Momentum — ideas developed over time" | — (distinct cadence) |
history (show-notes-history) | "Recently built notes" | — (utility) |
Finding F2 (biggest surface win). home + knowledge-dashboard + slipbox-health all answer "what's my state / what next." → Phase 2: merge the three into Home + one Health panel; keep every metric as a Home section. Finding F3. discoveries + resurface both surface connections. → Phase 3: one Discovery view. Finding F4 (minor). knowledge-map + concept-nav are two graph explorers; candidates to unify as two modes of one Graph view (lower priority).
3. Adopt-a-workflow — five overlapping paths (the onboarding-friction cluster)¶
| Path | What it installs | UX | Overlap |
|---|---|---|---|
| Community flow tab | a flow, via clipboard → paste on canvas | 2-hop, clunky | superseded by systems |
| Community system tab (#213) | a .zftemplate = canvas + steps, one click | one click | the canonical path |
install-starter-flows | the 4 classic note-type flows + a composed showcase | command | removed — superseded by systems |
install-methodology-package | a bundle of flows (the Zettelkasten package) | command | removed — superseded by systems |
import-canvas-template | a local .zftemplate from disk | command (desktop) | same format as systems |
Finding F5 (highest ROI — the #74 pain). Five ways to "get a workflow." → Phase 1: Systems Gallery is the one adoption path; present starter flows + the package as systems, retire the clipboard flow tab (kept viewable/legacy), fold the two install commands into the gallery. First-run nudges a system.
4. Community browser resource types¶
step · action · markdown · flow · system. flow is now redundant with system (F5). The other three are fragments (compose a flow) and stay. → Phase 1 hides/retires the flow tab.
5. Actions — the honest-set cluster¶
The action registry is grouped by capability (#152: Manipulation · Relations · Knowledge · Research · AI). Two are no-ops when authored into a template because their target is a build-time-fixed note path that a shipped template can't know:
| Action | Why it's a no-op in a template |
|---|---|
create-semantic-relation | target is fixed at authoring time; empty ⇒ writes nothing |
attach-source | reads a static source; empty ⇒ writes nothing |
Finding F6. These are offered in the picker but silently do nothing in a shipped system. → Phase 4: make them interactive-only or drop them from the offline-authorable set. (The deterministic find-related/suggest-link + the new remove-relation command cover the real relation jobs.)
6. Step configuration — dual format¶
| Format | Where | Status |
|---|---|---|
.md frontmatter zettelFlowSettings (file-node steps) | modern; what the Systems Gallery + export use | canonical |
Inline canvas node zettelflowConfig (text/group nodes) | legacy inline config | dual-path complexity; root of #226 |
Finding F7. Two config sources → maintenance cost + the hot-reload bug (#226, config not refreshed when the .canvas changes). → Phase 5: standardize on frontmatter, deprecate inline.
7. Settings surface¶
DEFAULT_SETTINGS toggles, by audience:
| Setting | Default | Audience |
|---|---|---|
ribbonCanvas / editorCanvas | "" | beginner-critical (the flow won't run until set — the #74 wall) |
events.enabled | off | advanced |
ai.* | off | advanced (AI is one action, never required — manifesto) |
timeline.enabled | off | advanced |
journal.enabled | on | benign (path-free counts) |
relations.parseInlineRelations | runtime (desktop on / mobile off) | advanced |
lifecycle.*Property | state/created/last-reviewed | advanced (no lock-in) |
uniquePrefix*, jsLibraryFolderPath, foldersFlowsPath, createInCurrentFolder | see defaults | mixed |
Finding F8. The one setting that blocks first use (ribbonCanvas) sits among many advanced toggles with equal weight. → Phase 6: sane defaults + first-run that sets the canvas by installing a system; group advanced toggles under "Advanced."
8. Consolidation summary (the plan, one row per cluster)¶
| Cluster | Today | One primary path (consolidate & hide) | Phase |
|---|---|---|---|
| Adopt a workflow | 5 paths | Systems Gallery (one click) | 1 |
| Observability | home + dashboard + slipbox-health | Home + one Health panel | 2 |
| Discovery | discoveries + resurface | one Discovery view | 3 |
| Graph explore | knowledge-map + concept-nav | one Graph view (two modes) | 2/later |
| Relation actions | + 2 template no-ops | interactive-only / hidden | 4 |
| Step config | frontmatter + inline | frontmatter only | 5 |
| Settings | flat toggles | defaults + Advanced group | 6 |
Nothing above is deleted — each duplicate keeps working, just no longer competes for the front door.