Skip to content

Task arash 20260507 222028 504938

title: "Sketch handbook outline + draft chapter 1 ("Interactivity as a research medium")" date: 2026-05-07 timestamp: 20260507-222028-504938 status: done result_note: /storage2/arash/worklog/workflow/captures/20260511-161148-0aaf31/note.md completed: 2026-05-11T16:11:52+02:00 actionable: true prompt: "" source_note: "" project_primary: "" priority: medium due: "" goal: "" blocked: false blocked_by: "" tags: [handbook, writing, chapter-1]

SCOPE UPDATE (2026-05-11)

This task originally bundled "sketch outline + draft chapter 1." The outline portion is discharged: the stack-axis outline now lives at docs/handbook/_outline.md (produced by the stack-axis spec task on 2026-05-08). The original 7-chapter substantive sketch below is superseded by the stack-axis chapter list (10 chapter directories, 33 sub-chapters).

The remaining work is the prose draft of what's now 00-frame/, which is the new home of the "frame chapter" concept. 00-frame/ is split into three sub-chapter files (already stubbed on disk; see docs/handbook/00-frame/):

Original chapter-1 concept New sub-chapter (stack-axis)
The argument (workflow as manipulable object) 00-frame/why-this-stack.md
The 7-paradigm taxonomy + the gap + reusable media forms 00-frame/why-interactivity.md
Honest limits + Quantomatic warning 00-frame/single-author-fragility.md

Do not create a 01-interactivity-as-medium/ directory. Do not rewrite _outline.md. Do not touch the 7-chapter sketch below — it's historical record.

Task (rescoped)

Replace the H1+stub content in each of the three 00-frame/ sub-chapter files with prose drafts, using the Deep Research synthesis as the conceptual frame.

Source PDF: docs/reference/research/Interactive Mathematics Beyond the Static Page.pdf (lands via the prior queued task task-arash-20260507-222003-098400.md). If the PDF is not on disk at that path when this task runs, abort with a clear error rather than hallucinating its content.

Per sub-chapter — what to draft

00-frame/why-this-stack.md (~600–900 words) - The argument: research practice has reached a maturity threshold where the workflow itself wants to be a manipulable, inspectable object — not just the final figures or the raw data. Static prose is to research practice what static images are to complex analysis. - The stack as a coherent open-science substrate: name the seven components (BIDS, DataLad, Snakemake, Marimo, Quarto/MkDocs, projio, agentic on top), one short paragraph each on what each contributes. - Why projio fills the missing layer: existing tools cover individual computations; the whole workflow as a manipulable object is uncovered. - Anchor to the rest of the handbook: this chapter's vocabulary recurs throughout (cite the outline §A chapter list).

00-frame/why-interactivity.md (~700–1000 words) - The 7-paradigm taxonomy from the Deep Research PDF, translated from mathematics to research workflow. Reproduce the table (use the version in the idea note docs/log/idea/idea-arash-20260507-221835-382557.md §"Conceptual frame"). - The gap argument: per the PDF, operator theory is math's interactivity gap; analog here is the whole research workflow as a manipulable object. - Reusable media forms — name three the handbook will use: workflow trace, permission scope diagram, goal critical path. - Placeholder for the marimo-WASM explorable (E1). Leave a clearly-marked iframe placeholder div with a TODO: E1 HTML comment. The real prototype lands via task task-arash-20260507-222051-589638.md. Do not draft a fake explorable.

00-frame/single-author-fragility.md (~400–600 words) - Quantomatic precedent (from PDF): "elegant research software can become historically important before it becomes infrastructurally stable." - Direct application: projio + worklog are single-creator today. - The PDF's prescription: code + docs + examples + community governance. The handbook is the docs+examples leg; the workshop is the start of community. This makes the handbook+workshop pair part of projio's survival strategy, not just outreach. - Honest limits: don't pretend the system is stable. Cite forward to 99-honest-gaps.md (also a stub on disk).

Constraints

  • Prose only. No new chapter files. No directory creation outside what already exists.
  • Preserve each stub's existing front-matter "Sources & anchors" note (the admonition block at the top of each file). Append prose below the existing "## Frame" line and replace the "## TBD" section.
  • Don't draft 99-honest-gaps.md — that's a separate task (per stack-axis roadmap §3).
  • Don't build marimo-WASM — E1 is task D (task-arash-20260507-222051-589638.md).
  • No bibliography wiring — citing the Deep Research PDF by file path is sufficient (it's not in the formal bib).

Acceptance

  • Three files updated: why-this-stack.md, why-interactivity.md, single-author-fragility.md — each with prose draft per above word targets
  • Existing stub frontmatter / admonition / outline cross-links preserved
  • mkdocs build --strict passes after edits (run with conda run -n rag python -m mkdocs build --strict per current env layout; minor INFO notes about pre-existing notio task-note typos are not blocking)
  • Reference to Deep Research PDF present in each chapter

Original outline sketch (HISTORICAL — superseded by stack-axis outline)

Suggested outline (working draft, refine)

  1. Interactivity as a research medium — frame chapter (this task)
  2. Reproducible foundations — BIDS, DataLad, Snakemake (workshop day 1)
  3. The agentic layer — Claude Code, MCP, projio scaffolding (workshop day 2 morning)
  4. Working with the agent — context, routing, cost, safety, when to verify (day 2 afternoon)
  5. The projio ecosystem — codio, biblio, figio, notio, manuscript (day 3 morning)
  6. Worklog as orchestrator — goals, tasks, scheduling, dispatch, multi-project (day 3 afternoon)
  7. Field notes — case studies, post-mortems, evolving practice (open-ended)

Adjust as needed; the handbook isn't bound to mirror the workshop exactly.

Chapter 1 specific content

Anchor in the Deep Research synthesis (see idea note docs/log/idea/idea-arash-20260507-221835-382557.md). Key beats:

  1. The argument: research practice is now reaching a maturity threshold where the workflow itself wants to be a manipulable, inspectable object — not just the final figures or the raw data. Static prose is to research practice what static images are to complex analysis.

  2. The 7-paradigm taxonomy translated from math to research workflow (table in the idea note). Use this as vocabulary for the rest of the handbook.

  3. The gap (per the Deep Research): tools exist for individual computations (Jupyter, Snakemake, DataLad), but the whole workflow as a manipulable object is uncovered. projio + worklog + this handbook are filling that gap.

  4. Reusable media forms: introduce the forms the handbook will use throughout — workflow trace, permission scope diagram, goal critical path.

  5. A live example: an embedded marimo-WASM cell where the reader changes a single parameter (e.g., a task graph definition) and watches the worklog scheduler dispatch them in dependency order. Prototype this in a separate task, drop into chapter 1 once it works.

  6. Honest limits: the doc's caution on visual systems misleading when discretization artifacts get confused with mathematics — analog warning for our case: the agent's confident output can mislead when the underlying provenance is broken.

Acceptance

  • Outline committed to docs/handbook/_outline.md (or whatever projio's handbook structure becomes)
  • Chapter 1 first draft in docs/handbook/01-interactivity-as-medium/index.md (or .qmd)
  • Reference to deep-research PDF
  • Placeholder for marimo-WASM explorable (real prototype in separate task)

Reference

  • Deep Research PDF (after migration task): projio/docs/reference/research/Interactive Mathematics Beyond the Static Page.pdf
  • Architectural and conceptual frame: idea note docs/log/idea/idea-arash-20260507-221835-382557.md