Skip to content

Phase 2b — Expand the Explanation stubs #2029

@mesejo

Description

@mesejo

Part of #2023. Prereq: Phase 1 complete (#2026, #2027).

Why

Several "why does Xorq do this?" concept pages are stubs or thin. These give
users mental models and are core to the agent/catalog/executable-memory spine.

Pages

docs/concepts/understanding_xorq/why_deferred_execution.qmd

Currently a 6-line stub. Target ~800–1200 words covering:

  1. What deferred execution means in Xorq (builds a graph, not immediate results).
  2. Why it matters for ML pipelines (full-pipeline optimization, cross-engine routing).
  3. Concrete eager-vs-deferred example showing the behavior difference.
  4. The tradeoff — added complexity; when to call .execute() immediately.
  5. Connection to caching — deferred graph = known structure = cacheable nodes.

Source the "why" framing from the deferred-execution tutorial and expand into
standalone explanation.

docs/concepts/understanding_xorq/intelligent_caching_system.qmd

  • Read first. If already substantive (>500 words of prose), skip. If thin or
    tutorial-style, expand the "why" sections.

docs/concepts/understanding_xorq/why_content_addressed_artifacts.qmd (new)

Cover:

  1. What content-addressed hashing is (deterministic hash of the computation, not of time).
  2. Why Xorq uses it (reproducibility, cache validity, artifact identity).
  3. What it means in practice (same pipeline = same hash = reuse existing artifact).
  4. Connection to the catalog model.

Done when

  • why_deferred_execution.qmd is >=800 words with a concrete example.
  • intelligent_caching_system.qmd assessed and expanded if needed.
  • why_content_addressed_artifacts.qmd written.
  • quarto render passes, no broken links.

Terminology gate

No-cloud language (per epic). Catalog = git repo of build artifacts.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions