Agent-Era Data Analysis Workflow: Reviewable Deliverables, Collaboration, and Execution Authorization

Methodology answer A: AI does not replace the analysis process; it turns the process into reviewable artifacts and explicit execution authorization. For knowledge governance, see Governable Agent Memory. For operations, see User Guide §10–12.

Series Position

For the complete guide, see Series Guide and Product Positioning.

1. The Core Judgment: AI Will Not Replace the Analysis Process, Only Reshape It

The essence of data analysis has not changed: pose questions, understand the data, test hypotheses, form conclusions, and be accountable to stakeholders. What changes is the interface—from "asking a question and getting an answer in a chat window" to "leaving behind queryable SQL, an editable Plan, and a sign-off-ready Report in an IDE."

Lantide Data's product assumptions are:

• Analysis is not a one-off answer, but a set of deliverables that can be discussed, versioned, and executed.
• Humans retain the pace and authorization; the Agent explores, drafts, and executes, but cannot press the "start running the formal analysis" switch on its own.
• Collaboration happens on documents (annotations, Plan state), not just in conversation bubbles.

2. Quick Analysis and Project Analysis

Simple SQL Q&A (such as how to write a piece of syntax) does not force a mode choice. When there is analytical intent, in Quick mode the Agent first asks whether you want a quick analysis or to create a project. For details, see §12.5.

When to use which mode (decision points):

One-off query / column exploration / no sign-off deliverable needed   → Quick Analysis
Need to review hypotheses, version the Plan, formal Report/HTML        → Project Analysis (focus a project first)
Project already focused                                               → Go straight into the project loop, no longer asking about mode

Pipeline stage mapping (see Series Guide §1 "An Analyst's Day"):

3. Why SQL-first: Analysis, Maintenance, and Collaboration

Lantide Data uses SQL as the primary delivery language for analytical work—not because the engine happens to support DuckDB, but because in modern analysis practice, the part most worth preserving, maintaining, and collaborating on is the definitions and data retrieval.

The following explains this from three angles: during analysis, definition is the contract; during maintenance, SQL is diffable and rerunnable; during collaboration, discussion happens on queryable artifacts.

Analysis: Definition Is the Contract

Analysis quality depends on "what this number means," not on whether the code is written elegantly. How is an active user defined? How are the user_ids from two sources aligned? Will this JOIN fan out? Such questions are most directly expressed with relational algebra: FROM, JOIN, WHERE, GROUP BY are exactly how you write a definition contract.

A Plan is naturally a SQL specification—it states what to query, which tables to use, and how to validate—rather than the execution order of a string of notebook cells. Analysis is not a one-off answer, but a set of discussable hypotheses and evidence; SQL makes hypotheses citable and refutable.

Analysis Quality: Get the Numbers Right First, Then Talk About Pipeline Shape

SQL-first does not mean "break everything into a DAG." The true priority order is:

1. First clarify the question, denominator, time window, and business definition.
2. Confirm data grain, columns, JOIN keys, and possible fan-out.
3. Use the minimal verifiable SQL to prove the metric logic is correct.
4. Check whether the output columns and step names are consistent—for example, a "product category analysis" should produce a category column.
5. Only at the end decide whether a persist tab, cache, or Source Run is needed.

Therefore, cache / DAG is a reusable and reviewable optimization capability, not the minimum condition for analytical credibility. If a multi-table JOIN is one-off and the definitions are clear, plain SQL can also be the right choice; only when intermediate results will be reused, need colleague review, or must be rerun after upstream changes is it worth upgrading to a persist-tab DAG.

Maintenance: Diffable and Rerunnable

Maintaining an analysis means maintaining whether, six months later, you can still explain clearly how this number came about.

• Declarative logic is easy to review: changing a single WHERE or JOIN condition, the diff points straight at the definition change, rather than reconstructing the mental model along imperative code.
• Dependencies are explicit: FROM "clean_orders" JOIN "dim_user" writes the intermediate assumptions down on paper; the df2, df3 in a notebook are implicit state.
• Clean rerun semantics: the same SQL, the same set of tables → predictable results; fewer "why is it different when I run cell 7 first" issues caused by cell execution order.
• Close to the team's definition language: reusable definitions often end up existing as warehouse SQL / a semantic layer; definitions polished in SQL are easier to promote into team assets than those hidden in one-off Python.

Collaboration: Happens on SQL Tabs and the Plan

Collaborative analysis often fails because the conclusion is in the slide deck while the logic is on someone's laptop; charts can be shared, but the definitions cannot be discussed. The table below explains how SQL-first responds to common collaboration needs:

Charts can be shared; definitions must be discussable. This contrasts with the Julius-style Harness (trading hidden code for speed) in Series Guide §1: we choose to expose SQL in exchange for governability.

Division of Labor with Python

It is not that Python is unused, but that Python is not made the default, unreviewable carrier of analysis:

Statistics and ML run on already-reviewed clean tables, while data retrieval still goes through SQL—see §12. What is rejected is the default path of "the model casually writing pandas in the conversation and discarding it after running."

Boundaries (We Do Not Claim to Replace Everything)

• Highly programmatic, custom algorithms, and heavy exploratory notebooks → Jupyter / Cursor and the like remain reasonable; what Lantide fills is analysis that needs governance and sign-off.
• Non-tabular, NLP, deep learning → not the primary scenario.
• We do not do enterprise-grade Silver ETL scheduling; for the positioning of intermediate results within the workspace, see Unified Query Layer §7.

Engineering Landing (Briefly)

The above principles are carried by the in-IDE SQL tabs, the Plan contract, and the Unified Query Layer (logical table names, materialization, Source Run lineage); DuckDB / sqlglot details are not expanded here.

4. Plan / Report: The Markdown Contract

Within a project, documents are divided into Plan (pre-execution contract) and Report (post-execution deliverable), usually paired by number, for example 01_plan.md / 01_report.md.

The Plan states what to query, which tables to use, and how to validate—consistent with SQL-first in §3: a pre-execution definition contract, not a notebook execution order.

Design goals:

1. The Plan is the pre-execution contract — what to query, which tables to use, how to validate, must be spelled out before execution.
2. The Report is the post-execution deliverable — conclusions and evidence go into the document, not just the chat log.
3. One-to-one pairing — a new analysis should get a new Plan, avoiding overwriting an old Report.
4. An Executed Plan is locked — for historical traceability; subsequent iterations open a new Plan.
5. HTML is a second kind of deliverable — see §5; it coexists with report.md.

For project files, archiving (Archived docs), and focus mode, see §11.

Four Plan states (system-internal codes such as PlanPlanning, etc.; product language is used here):

The frontend indicator syncs with the backend state and determines the available tool set (see AI Agent Architecture). When assumptions or data conditions change, use Stop & Replan rather than marking unfinished work Executed—see §11.6.

flowchart LR
  planning[Planning_annotatable]
  execute[User_Execute]
  executing[Executing_run SQL]
  report[add_report]
  executed[Executed_lock Plan]
  stopped[Stopped_keep partial outcome]
  planning --> execute --> executing --> report --> executed
  planning --> stopped
  executing --> stopped

Reference docs (Separate from Plan / Report)

Besides Plan / Report, a project can contain Reference files—holding the reference ontology such as column mappings, status-code dictionaries, and join explanations, which are large and rarely rewritten wholesale. Design trade-offs:

Creation paths: create an empty shell with New Reference, let the Agent create one natively, or import a local document through the governed import path. Native creation is available only in Project Focused or Plan Planning and requires one-submit confirmation. Update Intro can go through the Agent's propose_knowledge approval or be written manually by the user. An archived Reference does not trigger read_reference by default. Project / Workspace exports include References and their index; Compare view can open a Reference read-only (with no annotation sidecar). For operations, see §11.3.1; for onboarding, see Learn: Reference docs.

Stopping is not completing: when data conditions or decision assumptions change during formal execution, use Stop & Replan. The old Plan retains its stop reason, partial outcome, and formal evidence; the replacement Plan must pass the normal quality and execution contract before the user Executes it. Analysis Lineage links the Plan, Markdown Report, and HTML Report so reviewers can trace this evidence chain and see missing or ambiguous links without reconstructing it from chat history.

5. HTML Report: A Second Kind of Deliverable

Besides the Markdown Report, you can produce a standalone .html from the Report, to read, share, or export in a browser.

Product positioning:

• Generate / Re-generate: based on layout (Standard / Presentation), style presets, CDN/Chart.js and other configurations, the Agent produces complete HTML.
• Open Report / Export HTML Report: browse locally or save a snapshot (Electron export).
• Post-hoc edits: in the Report tab or, via activate_html_editing, in a non-Report tab, ask the Agent for block/style patches; a full layout overhaul should still Re-generate.
• Quick Edit HTML: the user manually edits a single block, with a content hash to prevent concurrent overwrites; Live Preview can be opened for hot reload.

Contract requirements (such as data-report-contract="1", a single #report-styles, data-text-id blocks) and tool behavior are explained in AI Agent Architecture §7. For step-by-step instructions, see User Guide §10.

6. Plan / Report Annotation: Writing Consensus into the Document

Annotation binds review comments to the original text and makes them input for the Agent's next round of revisions.

Storage model: select text in Preview → the annotation is written to a *.annotations.json sidecar, and an id-only <mark data-annotation-id> is written into the Markdown body; the editor maps the body mark and the right-side card bidirectionally. Old data-comment inline marks are automatically migrated to the sidecar on open (the metadata does not contain anchor.span; keeping the body id-only is still planned). Nested annotations are not supported.

Resolve Comments: a one-click toolbar action that asks the Agent to update the document according to all open annotations (equivalent to manually saying "handle the annotations"). In locked states such as Executing / Executed, the body is read-only, but the annotation margin remains operable.

State and lifecycle: Open → Agent Resolve → Resolved → can be Archived (history kept in the sidecar dismissed[]); Reopen can restore a Resolved one. When the body mark is lost, it becomes orphaned (the main-window UI marks it Anchor outdated)—it needs Re-anchor to re-highlight; View changes provides a Before/After comparison.

Compare view: read-only display of sidecar annotations and highlights, and the View changes Popover; it cannot edit, delete, or Re-anchor—collaborative editing stays in the main window. See §11.10.3.

The Agent obtains the on-disk body containing id-only marks and the sidecar annotations via read_plan / read_report; batch processing goes through resolve_annotations (atomically writing back the sidecar + body marks)—for the implementation, see Prompt and Context Engineering §11. For operations, see §11.7–11.9.

Report tables also support Copy for Excel (TSV + BOM), which differs from the SQL result Export—see §11.5.2.

7. The Most Important Boundary: The Agent Cannot Press Execute on Its Own

Execute is an explicit user authorization: it switches the Plan to Executing and triggers the Agent to execute according to the Plan. The Agent must not, via tools or conversation, do anything equivalent to "the user has pressed Execute."

This boundary distinguishes:

• Exploration and drafting (reading tables, validating SQL, editing the Plan)
• Formal execution of the analysis (requires the Executing state and the user-selected execution mode)

If the Agent could start running on its own, stakeholder sign-off would lose its meaning: the hypotheses on the Plan may not yet be fully reviewed, annotations may still be attached to the original text, yet the formal statistics have already produced a Report in the background—and the analyst cannot account to the team for "who approved this number, and under what premises." Therefore Execute must be an observable human action, not an intent the model infers on its own.

The Planning stage must not run formal statistics or activate_analysis; the methodology guardrails are written at the Prompt layer (Prompt and Context Engineering).

8. add_report: Completing the State Transition with a Deliverable

After execution completes, the Agent produces the Report in one shot via add_report and marks the corresponding Plan as Executed. This is a delivery event on the state machine, not a casual edit of a Markdown file.

• A new Plan executes → a new Report; it does not update the old Report.
• Only when the user annotates or explicitly requests it is an existing Report section revised (incremental editing preferred).

9. Foreground / Background / Hybrid

After the Plan enters Executing, the Agent asks once about the execution preference via ask_user:

Within the same conversation, an already-expressed preference is not asked again. For the materialization strategy of background run_query and the persist / agent cache semantics, see Prompt and Context Engineering §7 (semantic contracts) and Unified Query Layer §8.1 (strategy table); right-click Data → Cached and choose View SQL to review the source of any cache.

10. ask_user: Turning Human Decisions into an Agreement

When it needs to choose a mode, confirm the execution method, decide whether to continue after the exploration quota is used up, and so on, the Agent calls ask_user, and the frontend shows options or a free-text field; the backend pauses ReAct until a reply or timeout (about 5 minutes). Continuing after the exploration quota also goes through this agreement—see AI Agent Architecture §4.2.

This turns the "product flow" from a suggestion in the prompt into an observable interaction event. For operations, see §12.7.

11. Analysis Quality Guardrails

The analysis quality guardrails collaborate across three layers: identify the scenario (A/B, funnel, anomaly, etc., adding checkpoints in the Plan and writing limitations in the Report) → ask_user confirmation (statistical parameters, execution mode, and other decisions a human must call) → activate_analysis execution (running built-in statistics/ML tools on already-reviewed clean tables). The Planning stage should not skip the first two steps and run statistics directly; tool availability is filtered by the state matrix (see AI Agent Architecture §3).

For general business analysis, the minimum quality line is not "whether there is a DAG," but whether the report is credible. New Plans and Reports validate their required reader-facing structure and retain a verification receipt bound to the semantic section mapping and content digest. This does not replace human review, but it prevents work that lacks decisions, evidence, scope, or limitations from being finalized directly. The release smoke currently uses the following signals as a hard gate:

• Whether a Plan is created first, then todos are built according to the Plan, and finally a Report is produced.
• Whether the SQL / tool has no obvious error loops.
• Whether the report clearly states the necessary content for the scenario, for example a funnel's stage definition, denominator, and largest drop-off point.
• Whether the report has concrete numbers and limitations, rather than just leaving a chat summary.
• Whether metrics such as rate, funnel, retention, and finance retain both numerator / denominator and a grain explanation.

DAG, Source Run, and the Execution Strategy block are now soft signals: nice to have, but their absence should not block a credible analysis.

Document revisions prioritize paragraph-level incremental editing, reducing wholesale overwrites and annotation misalignment. For operations, see §12.9–12.10.

12. Anti-patterns

13. Capability Overview

14. Closing

The core of Lantide Data's analysis workflow is turning "asking the AI a question" into "leaving behind a set of reviewable, authorizable, rerunnable deliverables." The Execute boundary and the SQL-first definition contract are the two pillars of this methodology—the former guarantees the human's pace, the latter guarantees the carrier of collaboration.

The precipitation of definitions across conversations belongs to another dimension: see Governable Agent Memory. To understand how the model sees the Plan, annotations, and knowledge, read Prompt and Context Engineering next.