Skip to content
Crosswalker
🚧 Early alpha — building the foundation. See the roadmap →

Challenge 32: Intuitive query UX — how does a user go from intent to a working .base file?

Created Updated

Why this exists

Section titled “Why this exists”

The user’s repeated framing was: “the query engine should be intuitive.” That word carries weight. v0.1.6’s commitment is hand-authored YAML recipes + one custom Bases view — it’s not intuitive, it’s expert-friendly. Ch 32 asks: how do we make this intuitive for non-technical users (compliance auditors, GRC analysts, ontology-mapping researchers, library-science taxonomy editors)?

User journey to investigate:

  1. User has intent: “show me coverage of NIST × ISO”
  2. User picks (or composes) a recipe
  3. User authors (or selects) a .base file
  4. User sees the result

Today, steps 2-3 require knowing the recipe schema and the .base file format. That’s a steep learning curve. Ch 32 designs UX patterns to lower it.

What we already have

Section titled “What we already have”
AssetToday’s UX
Import wizardMulti-step modal for IMPORT (covered by features/import-wizard.mdx). Doesn’t handle queries.
Recipe loader (v0.1.6 pending)YAML files in _crosswalker/recipes/; user finds them by file browse
crosswalkerPivot view (v0.1.6 pending)Selected from Bases view-picker dropdown
Concept docsDocuments the schema; not interactive
MarketplaceOut of scope until v0.3+

The gap: nothing scaffolds the user from intent to working query.

What to investigate

Section titled “What to investigate”

1. Cross-reference declarative-query UX in adjacent products

Section titled “1. Cross-reference declarative-query UX in adjacent products”

For each tool, document: how does a non-technical user go from intent to query? What pattern? What works? What doesn’t?

  • Looker Explore — point-and-click query builder; measures + dimensions; saved views
  • Tableau — visual drag-and-drop pivot/chart designer
  • Power BI — measure + visualization picker
  • dbt Cloud Insights — query authoring inside the dbt UI
  • Metabase — question builder (point-click) vs SQL editor toggle
  • Notion databases — “create a view” dialog with type picker (table/board/timeline/calendar/gallery)
  • Airtable views — similar to Notion; view types selected from a menu
  • BioPortal Mappings UI — how does a researcher find mappings between two ontologies?
  • NIST OLIR portal — how does a user search the OLIR catalog of crosswalks?
  • OxO2 (EBI) UI — how does a user query for cross-ontology mappings?
  • Obsidian Bases UI itself — how does Obsidian present .base file authoring?

2. Three UX patterns for Crosswalker

Section titled “2. Three UX patterns for Crosswalker”

Argue between three plausible UX patterns:

Pattern A: Wizard (multi-step modal)

Section titled “Pattern A: Wizard (multi-step modal)”

Like the import wizard. User clicks “New Query Recipe” → wizard asks: what shape? what ontologies? what edge predicate? what cell op? Wizard generates a .base file.

Pros: structured; works for novices; reuses existing wizard infrastructure Cons: rigid; doesn’t surface the recipe library (user must know what they want)

Pattern B: Recipe picker (browse-and-customize)

Section titled “Pattern B: Recipe picker (browse-and-customize)”

Marketplace-style picker. User browses canonical recipes (“Coverage Matrix”, “Crosswalk Density”, “Freshness Heatmap”), picks one, customizes parameters. Generates a .base file from the recipe.

Pros: discoverability of canonical patterns; one-click for common cases Cons: requires marketplace; users with novel queries can’t easily start from scratch

Pattern C: Inline editor (live .base file with autocomplete)

Section titled “Pattern C: Inline editor (live .base file with autocomplete)”

User opens a .base file directly; gets autocomplete on query: block fields (shape values, primitive options); validation errors inline.

Pros: power-user friendly; no UI to maintain beyond schema-driven hints Cons: requires schema knowledge; not novice-friendly

Pattern D: Hybrid (recipe-picker for common; wizard for novel; inline for power users)

Section titled “Pattern D: Hybrid (recipe-picker for common; wizard for novel; inline for power users)”

Combine all three. Recipe picker as primary entry point; “Build from scratch” → wizard; “Edit YAML” link → inline editor.

Argue which pattern (or hybrid) best fits Crosswalker’s user base across compliance auditors, GRC analysts, ontology researchers, library-science taxonomy editors.

3. Mobile vs desktop UX

Section titled “3. Mobile vs desktop UX”

Bases works on mobile (Obsidian 1.10+). What does query-building look like on mobile?

  • Wizard modal: adapts well
  • Recipe picker: fine on mobile
  • Inline YAML editor: poor on mobile (small screens; no autocomplete)

Argue which patterns degrade gracefully and which require desktop-only.

4. Recipe discoverability

Section titled “4. Recipe discoverability”

How does a user find the right recipe for their intent?

  • File-system browse (boring)
  • Categorized recipe registry (“Compliance” / “Threat intelligence” / “Biomedical” / “Library”)
  • Search-by-keyword (“show me recipes about evidence freshness”)
  • Recommendation engine (“users who ran X also ran Y”)

What’s the v0.1.6-feasible bar? What’s v0.2+?

5. Learning curve to authoring novel recipes

Section titled “5. Learning curve to authoring novel recipes”

For a user who needs a query NOT covered by any canonical recipe — what’s the path?

  • Read the recipe schema
  • Copy a similar recipe and modify
  • Use a wizard
  • Ask an LLM to generate
  • Hire a Crosswalker consultant (joke, mostly)

What scaffolding (concept-docs / cookbook / tutorial / template gallery / LLM-assisted author / guided wizard) gets a non-technical user to a novel-but-correct recipe in under an hour?

6. Error handling and feedback loops

Section titled “6. Error handling and feedback loops”

When a recipe doesn’t validate, when a .base file produces empty results, when a crosswalkerPivot view fails to render — what does the user see? How do they recover?

Specific scenarios:

  • Recipe references an ontology ID that doesn’t exist in vault
  • Recipe specifies a primitive composition that has no result
  • .base file is malformed
  • Custom view fails to register (Bases plugin disabled)

7. Materialization UX (added 2026-05-08 per D1 lock)

Section titled “7. Materialization UX (added 2026-05-08 per D1 lock)”

Synthesis log D1 locked materialization for v0.1.6 (opt-in, manual-command-only). The Ch 28a § Materialization Lifecycle spec covers prevention (frontmatter contract; hand-edit prevention; conflict policy) but the click-time / read-time UX is not yet fully designed. Investigation areas:

  • Click behavior: when a user clicks a materialized file (e.g. _crosswalker/audit/2026-Q1/coverage-matrix.md), what should they see first? Live preview vs source view? Does the frontmatter banner actually surface to the reader visibly?
  • Coexistence with canonical files: Obsidian’s vault convention is “every file is canonical user content.” Materialized files break that assumption. How do users distinguish them at a glance? File-icon coloring? Folder visual treatment? CSS class injection (e.g. cssclasses: [crosswalker-generated] actually styled)?
  • Bases convention coherence: the user’s first-impression concern — “clicking on them and operating in obsidian is gonna be a little bit confusing for people who are used to certain conventions with obsidian bases”. What’s the expected mental model? Is it “this folder is generated; treat as read-only”? Or “these are normal files but you shouldn’t edit them”? Document the convention precisely.
  • Discovery: how do users find the materialized files? Folder browse? Bases view that lists crosswalker.materialized: true files? Command-palette index?
  • Staleness signaling: when the underlying junctions have changed since materialization, the file is stale. How does the reader see that? [!warning] Stale callout at top of body? Frontmatter stale_since: field that triggers a Bases formula highlight?
  • The deeper question (per D3): should derived projections (pivot tables, coverage matrices) ever be vault files at all? Junction notes are first-class evidence-link entities (an architectural commitment). But pivots are projections of those junctions. The user’s contrarian critique: “I question the premise of letting this plugin emit files in the first place… the benefits of having Obsidian is that with Obsidian Bases you’re attaching metadata to files and you don’t have to duplicate other files just to store metadata about those files.” Investigate whether opt-in materialization is the right minimum-viable surface, or whether there are alternative patterns (hover-preview, command-palette modal, side-panel view) that satisfy the “share with auditor” / “Publish parity” need without emitting files.

8. AI-agent assistance

Section titled “8. AI-agent assistance”

A meta-question: should Crosswalker explicitly support LLM agents authoring queries? Examples:

  • Agent inspects vault → writes a custom recipe for the user’s data
  • Agent translates natural-language intent (“show me NIST gaps”) → working .base file
  • Agent debugs why a recipe returned empty

This is increasingly the way Obsidian integrates with AI (per kepano/obsidian-skills). What’s the v0.1 minimum viable surface for agent-friendly query authoring?

Anti-patterns to reject upfront

Section titled “Anti-patterns to reject upfront”

The deliverable must NOT recommend:

  1. Building a custom drag-and-drop query builder — out of scope for v0.1; UI complexity unbounded
  2. Replacing Bases’ built-in view picker — Bases’ UI handles view selection; we just register custom view types
  3. Forking Looker / Tableau / Power BI UX — those are enterprise products; Crosswalker is a plugin
  4. Pre-generating thousands of canonical recipes — recipe marketplace is a v0.3+ concern
  5. Forcing all users through a wizard — power users should have a path to inline .base authoring
  6. A web-based query builder outside Obsidian — out of scope; everything stays in-vault
  7. An obsidian-native modal that fights Bases UI — Bases’ UX is the convention; align with it

Success criteria for the deliverable

Section titled “Success criteria for the deliverable”

The deliverable must produce:

  1. Cross-reference matrix — 8+ adjacent products × UX dimensions (entry point / authoring path / discoverability / mobile / errors / agent-friendliness)
  2. Pattern verdict — wizard vs recipe-picker vs inline vs hybrid; argued recommendation
  3. Mobile vs desktop UX matrix — what works where
  4. Recipe discoverability proposal — concrete v0.1 minimum + v0.2+ roadmap
  5. Learning-curve scaffolding plan — docs / cookbook / template gallery / LLM-assist
  6. Error-handling design — feedback loops for the 4+ scenarios listed
  7. Materialization UX design — click behavior, vault-coexistence pattern, Bases-convention coherence, staleness signaling, discovery path; argue for or against the contrarian “no materialization” path given the click-time UX cost (per D1 + D3 cross-references)
  8. AI-agent surface decision — what’s in v0.1.6, what’s deferred
  9. Recommended changes to v0.1.6 milestone scope (or explicit “no changes; this is v0.2+ work”)

Anchored references

Section titled “Anchored references”

Project context:

Adjacent UX references:

AI-agent integration:

Hand-off

Section titled “Hand-off”

Write the deliverable to docs/.../zz-research/YYYY-MM-DD-challenge-32-deliverable-a-<slug>.md. After deliverable lands: capture findings into a new concepts/query-ux.mdx page (or expand existing features/import-wizard.mdx) — TBD by deliverable; flip synthesis log §9 status Ch 32 row from ⏳ to ✅; archive this brief.